iriai-build 0.1.0

package/index.js

@@ -0,0 +1,1488 @@
+#!/usr/bin/env node
+// iriai-build — Socket Mode bridge between Slack and iriai planning pipeline.
+//
+// Routes Slack messages to signal files, watches signal files for agent responses,
+// posts them back to Slack. Manages the full feature lifecycle from [FEATURE] post
+// through planning pipeline to implementation kickoff.
+
+import { SocketModeClient } from "@slack/socket-mode";
+import { WebClient } from "@slack/web-api";
+import chokidar from "chokidar";
+import fs from "node:fs";
+import path from "node:path";
+import { spawn, execSync } from "node:child_process";
+
+// ─── Config ──────────────────────────────────────────────────────────────────
+
+const SLACK_APP_TOKEN = process.env.SLACK_APP_TOKEN; // xapp-... (Socket Mode)
+const SLACK_BOT_TOKEN = process.env.SLACK_BOT_TOKEN; // xoxb-... (Web API)
+const PLANNING_CHANNEL = process.env.SLACK_CHANNEL_ID; // #planning channel ID
+
+if (!SLACK_APP_TOKEN || !SLACK_BOT_TOKEN || !PLANNING_CHANNEL) {
+  console.error(
+    "Missing required env vars: SLACK_APP_TOKEN, SLACK_BOT_TOKEN, SLACK_CHANNEL_ID"
+  );
+  process.exit(1);
+}
+
+const PLANNING_BASE =
+  process.env.PLANNING_SIGNAL_BASE ||
+  path.join(process.env.HOME, "src/iriai/.planning");
+const IRIAI_TEAM_DIR =
+  process.env.IRIAI_TEAM_DIR ||
+  path.join(process.env.HOME, "src/iriai/iriai-team");
+const SCRIPTS_DIR = path.join(IRIAI_TEAM_DIR, "scripts");
+const IMPL_BASE =
+  process.env.IMPL_SIGNAL_BASE ||
+  path.join(process.env.HOME, "src/iriai/.implementation");
+const STATE_FILE = path.join(PLANNING_BASE, "lead", ".bridge-state.json");
+
+const ROLE_DIRS = {
+  pm: path.join(PLANNING_BASE, "pm"),
+  designer: path.join(PLANNING_BASE, "design"),
+  architect: path.join(PLANNING_BASE, "architect"),
+  "plan-compiler": path.join(PLANNING_BASE, "plan-compiler"),
+  lead: path.join(PLANNING_BASE, "lead"),
+};
+
+const ROLE_LABELS = {
+  pm: "PM",
+  designer: "Designer",
+  architect: "Architect",
+  "plan-compiler": "Plan Compiler",
+  lead: "Feature Lead",
+};
+
+// Pipeline order for planning roles
+const PIPELINE_ORDER = ["pm", "designer", "architect", "plan-compiler"];
+
+// ─── State ───────────────────────────────────────────────────────────────────
+
+// thread_ts -> { feature_slug, active_role, signal_dir, plan_summary_ts, impl_channel }
+let features = {};
+let watchers = [];
+
+// Track running role runner PIDs to prevent duplicate spawns
+// role -> child process pid
+const runningRoles = {};
+
+// Track implementation signal watchers (separate from planning watchers)
+let implWatchers = [];
+
+// Track running impl processes: key -> { pid }
+// Keys: "fl-<slug>", "team-<slug>-N", "role-<slug>-N-<role>", etc.
+const implProcesses = {};
+
+// ─── Clients ─────────────────────────────────────────────────────────────────
+
+const socketClient = new SocketModeClient({ appToken: SLACK_APP_TOKEN });
+const web = new WebClient(SLACK_BOT_TOKEN);
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function slugify(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 40);
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function saveState() {
+  ensureDir(path.dirname(STATE_FILE));
+  fs.writeFileSync(STATE_FILE, JSON.stringify(features, null, 2));
+}
+
+function loadState() {
+  try {
+    if (fs.existsSync(STATE_FILE)) {
+      features = JSON.parse(fs.readFileSync(STATE_FILE, "utf-8"));
+      console.log(
+        `Restored state: ${Object.keys(features).length} active features`
+      );
+    }
+  } catch {
+    console.warn("Could not load bridge state, starting fresh");
+    features = {};
+  }
+}
+
+function parseRole(text) {
+  const lower = text.toLowerCase();
+  if (lower.includes("@pm")) return "pm";
+  if (lower.includes("@designer")) return "designer";
+  if (lower.includes("@architect")) return "architect";
+  if (lower.includes("@compiler") || lower.includes("@plan-compiler")) return "plan-compiler";
+  if (lower.includes("@lead")) return "lead";
+  return null;
+}
+
+async function postToThread(channel, thread_ts, text) {
+  await web.chat.postMessage({ channel, thread_ts, text });
+}
+
+async function addReaction(channel, timestamp, reaction) {
+  try {
+    await web.reactions.add({ channel, name: reaction, timestamp });
+  } catch {
+    // Ignore — reaction may already exist or message may be gone
+  }
+}
+
+async function removeReaction(channel, timestamp, reaction) {
+  try {
+    await web.reactions.remove({ channel, name: reaction, timestamp });
+  } catch {
+    // Ignore — reaction may not exist
+  }
+}
+
+// Track the last user message ts per feature thread so we can remove :eyes: when agent responds
+// thread_ts -> last_user_message_ts
+const pendingUserMessages = {};
+
+// Bot's own user ID — populated at startup to filter self-reactions
+let botUserId = null;
+
+function findArtifact(filename) {
+  const planDir = path.join(IRIAI_TEAM_DIR, "implementation-plans", "current");
+  try {
+    const files = fs.readdirSync(planDir);
+    const match = files.find((f) => f.includes(filename) && f.endsWith(".md"));
+    if (match) return path.join(planDir, match);
+  } catch {
+    // Directory or file doesn't exist yet
+  }
+  return null;
+}
+
+async function uploadArtifact(channel, thread_ts, filePath, title) {
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    await web.filesUploadV2({
+      channel_id: channel,
+      thread_ts,
+      content,
+      filename: path.basename(filePath),
+      title,
+    });
+  } catch (err) {
+    console.error(`Error uploading artifact ${title}:`, err.message);
+    // Fall back to posting as text if upload fails
+    const content = fs.readFileSync(filePath, "utf-8");
+    const truncated = content.length > 3000
+      ? content.slice(0, 3000) + "\n\n_(truncated — full document in repo)_"
+      : content;
+    await postToThread(channel, thread_ts, `*${title}:*\n\n${truncated}`);
+  }
+}
+
+// Known repo paths in the monorepo
+const KNOWN_REPOS = [
+  "first-party-apps/directory/directory-backend",
+  "first-party-apps/directory/directory-frontend",
+  "first-party-apps/events/events-backend",
+  "first-party-apps/events/events-frontend",
+  "first-party-apps/subdomain-home/subdomain-home-frontend",
+  "first-party-apps/subdomain-home/subdomain-home-server",
+  "frontend-apps/iriai-app/iriai-app-bff",
+  "frontend-apps/iriai-app/iriai-app-frontend",
+  "packages/auth-python",
+  "packages/auth-react",
+  "platform/auth/auth-frontend",
+  "platform/auth/auth-service",
+  "platform/deploy-console/deploy-console-frontend",
+  "platform/deploy-console/deploy-console-service",
+  "platform/integration-engine/integration-engine-service",
+];
+
+function detectReposFromPlan() {
+  const planPath = findArtifact("implementation-plan");
+  if (!planPath) return [];
+
+  const content = fs.readFileSync(planPath, "utf-8");
+  return KNOWN_REPOS.filter((repo) => content.includes(repo));
+}
+
+// ─── Signal File Watching ────────────────────────────────────────────────────
+
+function watchAgentResponses() {
+  // Watch all role signal dirs for .agent-response files
+  const dirsToWatch = Object.values(ROLE_DIRS);
+
+  for (const dir of dirsToWatch) {
+    ensureDir(dir);
+  }
+
+  const watcher = chokidar.watch(
+    dirsToWatch.map((d) => path.join(d, ".agent-response")),
+    { ignoreInitial: true, awaitWriteFinish: { stabilityThreshold: 500 } }
+  );
+
+  watcher.on("add", handleAgentResponse);
+  watcher.on("change", handleAgentResponse);
+  watchers.push(watcher);
+
+  // Also watch for .done files (phase completion)
+  const doneWatcher = chokidar.watch(
+    dirsToWatch.map((d) => path.join(d, ".done")),
+    { ignoreInitial: true, awaitWriteFinish: { stabilityThreshold: 500 } }
+  );
+
+  doneWatcher.on("add", handleDoneSignal);
+  doneWatcher.on("change", handleDoneSignal);
+  watchers.push(doneWatcher);
+
+  // Watch for .question files (agent questions needing user input)
+  const questionWatcher = chokidar.watch(
+    dirsToWatch.map((d) => path.join(d, ".question")),
+    { ignoreInitial: true, awaitWriteFinish: { stabilityThreshold: 500 } }
+  );
+
+  questionWatcher.on("add", handleQuestionSignal);
+  questionWatcher.on("change", handleQuestionSignal);
+  watchers.push(questionWatcher);
+
+  console.log("Watching signal dirs for .agent-response, .done, .question");
+}
+
+async function handleAgentResponse(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, "utf-8").trim();
+    if (!content) return;
+
+    // Determine which role produced this response
+    const dir = path.dirname(filePath);
+    const role = Object.entries(ROLE_DIRS).find(
+      ([, d]) => d === dir
+    )?.[0];
+    if (!role) return;
+
+    const label = ROLE_LABELS[role] || role;
+
+    // Find the feature this role is currently working on
+    const feature = Object.entries(features).find(
+      ([, f]) => f.active_role === role
+    );
+
+    if (feature) {
+      const [thread_ts, featureState] = feature;
+      const channel = role === "lead" && featureState.impl_channel
+        ? featureState.impl_channel
+        : PLANNING_CHANNEL;
+
+      await postToThread(
+        channel,
+        thread_ts,
+        `*[${label}]* ${content}`
+      );
+
+      // Remove :eyes: from the user's message now that the agent has responded
+      const pendingTs = pendingUserMessages[thread_ts];
+      if (pendingTs) {
+        await removeReaction(channel, pendingTs, "eyes");
+        delete pendingUserMessages[thread_ts];
+      }
+    }
+
+    // Delete after posting
+    fs.unlinkSync(filePath);
+  } catch (err) {
+    console.error("Error handling agent response:", err.message);
+  }
+}
+
+async function handleQuestionSignal(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, "utf-8").trim();
+    if (!content) return;
+
+    const dir = path.dirname(filePath);
+    const role = Object.entries(ROLE_DIRS).find(
+      ([, d]) => d === dir
+    )?.[0];
+    if (!role) return;
+
+    const label = ROLE_LABELS[role] || role;
+
+    // Find the feature this role is working on
+    const feature = Object.entries(features).find(
+      ([, f]) => f.active_role === role
+    );
+
+    if (feature) {
+      const [thread_ts, featureState] = feature;
+      const channel = role === "lead" && featureState.impl_channel
+        ? featureState.impl_channel
+        : PLANNING_CHANNEL;
+
+      // Post verbatim with full attribution: role, phase/task context
+      const phase = featureState.active_role;
+      const slug = featureState.feature_slug;
+      await postToThread(
+        channel,
+        thread_ts,
+        `*[${label} — ${slug} / ${phase} phase]*\n\n${content}`
+      );
+    }
+
+    fs.unlinkSync(filePath);
+  } catch (err) {
+    console.error("Error handling question signal:", err.message);
+  }
+}
+
+async function handleDoneSignal(filePath) {
+  try {
+    const dir = path.dirname(filePath);
+    const role = Object.entries(ROLE_DIRS).find(
+      ([, d]) => d === dir
+    )?.[0];
+    if (!role) return;
+
+    const label = ROLE_LABELS[role] || role;
+
+    // Find the feature where this role was active
+    const feature = Object.entries(features).find(
+      ([, f]) => f.active_role === role
+    );
+    if (!feature) return;
+
+    const [thread_ts, featureState] = feature;
+
+    // Read .output if it exists
+    const outputPath = path.join(dir, ".output");
+    let output = "";
+    if (fs.existsSync(outputPath)) {
+      output = fs.readFileSync(outputPath, "utf-8").trim();
+    }
+
+    // Post phase completion
+    await postToThread(
+      PLANNING_CHANNEL,
+      thread_ts,
+      `*[Pipeline]* ${label} phase complete.${output ? ` Output: ${output}` : ""}`
+    );
+
+    // Artifacts are uploaded together when planning completes (postPlanForApproval)
+
+    // Advance to next role in pipeline
+    const currentIndex = PIPELINE_ORDER.indexOf(role);
+
+    if (currentIndex >= 0 && currentIndex < PIPELINE_ORDER.length - 1) {
+      // Advance to next planning role
+      const nextRole = PIPELINE_ORDER[currentIndex + 1];
+      const nextLabel = ROLE_LABELS[nextRole];
+      featureState.active_role = nextRole;
+      saveState();
+
+      await postToThread(
+        PLANNING_CHANNEL,
+        thread_ts,
+        `*[Pipeline]* Starting ${nextLabel} phase...`
+      );
+
+      dispatchToRole(nextRole, featureState.feature_slug, thread_ts);
+    } else if (role === "plan-compiler") {
+      // Plan Compiler done — post plan for approval (last planning step)
+      await postPlanForApproval(thread_ts, featureState);
+    }
+
+    // Clean up done/output signals
+    fs.unlinkSync(filePath);
+    if (fs.existsSync(outputPath)) fs.unlinkSync(outputPath);
+  } catch (err) {
+    console.error("Error handling done signal:", err.message);
+  }
+}
+
+// ─── Implementation Signal Handling ──────────────────────────────────────────
+// Phases 1, 4, 5, 6, 7, 8: Full implementation lifecycle from Slack
+
+function discoverImplSignalTree(slug) {
+  const featureDir = path.join(IMPL_BASE, "features", slug);
+  const tree = {
+    featureDir,
+    featureLead: null,
+    operator: null,
+    featureReview: {},
+    teams: {},
+  };
+
+  const flDir = path.join(featureDir, "feature-lead");
+  if (fs.existsSync(flDir)) tree.featureLead = flDir;
+
+  const opDir = path.join(featureDir, "operator");
+  if (fs.existsSync(opDir)) tree.operator = opDir;
+
+  const reviewDir = path.join(featureDir, "feature-review");
+  try {
+    for (const entry of fs.readdirSync(reviewDir)) {
+      const roleDir = path.join(reviewDir, entry);
+      if (fs.statSync(roleDir).isDirectory()) {
+        tree.featureReview[entry] = roleDir;
+      }
+    }
+  } catch { /* no review dir yet */ }
+
+  const teamsDir = path.join(featureDir, "teams");
+  try {
+    for (const team of fs.readdirSync(teamsDir).sort()) {
+      if (!team.startsWith("team-")) continue;
+      const teamDir = path.join(teamsDir, team);
+      if (!fs.statSync(teamDir).isDirectory()) continue;
+      const teamNum = team.replace("team-", "");
+      tree.teams[teamNum] = {
+        dir: teamDir,
+        orchestrator: null,
+        roles: {},
+      };
+
+      const orchDir = path.join(teamDir, "orchestrator");
+      if (fs.existsSync(orchDir)) tree.teams[teamNum].orchestrator = orchDir;
+
+      const rolesDir = path.join(teamDir, "roles");
+      try {
+        for (const role of fs.readdirSync(rolesDir)) {
+          const roleDir = path.join(rolesDir, role);
+          if (fs.statSync(roleDir).isDirectory()) {
+            tree.teams[teamNum].roles[role] = roleDir;
+          }
+        }
+      } catch { /* no roles dir */ }
+    }
+  } catch { /* no teams dir */ }
+
+  return tree;
+}
+
+function watchImplSignals(slug, thread_ts) {
+  const featureState = features[thread_ts];
+  if (!featureState) return;
+
+  const tree = discoverImplSignalTree(slug);
+  featureState.impl_signal_tree = tree;
+  saveState();
+
+  const flDir = tree.featureLead;
+  if (!flDir) {
+    console.warn(`No Feature Lead dir found for ${slug}`);
+    return;
+  }
+
+  // Watch Feature Lead's .agent-response → post to #impl channel
+  const responseWatcher = chokidar.watch(
+    path.join(flDir, ".agent-response"),
+    { ignoreInitial: true, awaitWriteFinish: { stabilityThreshold: 500 } }
+  );
+  responseWatcher.on("add", (fp) => handleImplAgentResponse(fp, slug, thread_ts));
+  responseWatcher.on("change", (fp) => handleImplAgentResponse(fp, slug, thread_ts));
+  implWatchers.push(responseWatcher);
+
+  // Watch Operator's .agent-response → post to #impl channel
+  if (tree.operator) {
+    const opResponseWatcher = chokidar.watch(
+      path.join(tree.operator, ".agent-response"),
+      { ignoreInitial: true, awaitWriteFinish: { stabilityThreshold: 500 } }
+    );
+    opResponseWatcher.on("add", (fp) => handleOperatorResponse(fp, slug, thread_ts));
+    opResponseWatcher.on("change", (fp) => handleOperatorResponse(fp, slug, thread_ts));
+    implWatchers.push(opResponseWatcher);
+  }
+
+  // Watch Feature Lead's .feature-complete
+  const completeWatcher = chokidar.watch(
+    path.join(flDir, ".feature-complete"),
+    { ignoreInitial: true, awaitWriteFinish: { stabilityThreshold: 500 } }
+  );
+  completeWatcher.on("add", (fp) => handleFeatureComplete(fp, slug, thread_ts));
+  implWatchers.push(completeWatcher);
+
+  // Watch .needs-restart across all agent dirs for handover
+  const allDirs = [flDir];
+  if (tree.operator) allDirs.push(tree.operator);
+  for (const team of Object.values(tree.teams)) {
+    if (team.orchestrator) allDirs.push(team.orchestrator);
+    for (const roleDir of Object.values(team.roles)) {
+      allDirs.push(roleDir);
+    }
+  }
+  for (const reviewDir of Object.values(tree.featureReview)) {
+    allDirs.push(reviewDir);
+  }
+
+  const restartWatcher = chokidar.watch(
+    allDirs.map((d) => path.join(d, ".needs-restart")),
+    { ignoreInitial: true, awaitWriteFinish: { stabilityThreshold: 500 } }
+  );
+  restartWatcher.on("add", (fp) => handleNeedsRestart(fp, slug, thread_ts));
+  implWatchers.push(restartWatcher);
+
+  console.log(`Watching impl signals for ${slug}: Feature Lead + ${allDirs.length} total dirs`);
+}
+
+// Phase 4: Route Feature Lead messages to #impl channel
+async function handleImplAgentResponse(filePath, slug, thread_ts) {
+  try {
+    const content = fs.readFileSync(filePath, "utf-8").trim();
+    if (!content) return;
+
+    const featureState = features[thread_ts];
+    if (!featureState) return;
+
+    const channel = featureState.impl_channel || PLANNING_CHANNEL;
+
+    // Detect gate evidence pattern for approval flow
+    const isGateEvidence = /gate\s*(evidence|summary|review)/i.test(content) ||
+      (/approve|reject/i.test(content.slice(-300)) && content.length > 200);
+
+    const result = await web.chat.postMessage({
+      channel,
+      text: `*[Feature Lead]* ${content}`,
+    });
+
+    // If this looks like gate evidence, track for reaction-based approval
+    if (isGateEvidence) {
+      featureState.gate_evidence_ts = result.ts;
+      featureState.gate_evidence_channel = channel;
+      saveState();
+      // Add reaction hints for approval
+      await addReaction(channel, result.ts, "white_check_mark");
+      await addReaction(channel, result.ts, "x");
+    }
+
+    // Remove :eyes: from pending user message
+    const pendingTs = pendingUserMessages[thread_ts];
+    if (pendingTs) {
+      await removeReaction(channel, pendingTs, "eyes");
+      delete pendingUserMessages[thread_ts];
+    }
+
+    fs.unlinkSync(filePath);
+  } catch (err) {
+    console.error("Error handling impl agent response:", err.message);
+  }
+}
+
+// Operator responses → post to #impl channel with [Operator] prefix
+async function handleOperatorResponse(filePath, slug, thread_ts) {
+  try {
+    const content = fs.readFileSync(filePath, "utf-8").trim();
+    if (!content) return;
+
+    const featureState = features[thread_ts];
+    if (!featureState) return;
+
+    const channel = featureState.impl_channel || PLANNING_CHANNEL;
+
+    await web.chat.postMessage({
+      channel,
+      text: `*[Operator]* ${content}`,
+    });
+
+    // Remove :eyes: from pending user message
+    const pendingTs = pendingUserMessages[thread_ts];
+    if (pendingTs) {
+      await removeReaction(channel, pendingTs, "eyes");
+      delete pendingUserMessages[thread_ts];
+    }
+
+    fs.unlinkSync(filePath);
+  } catch (err) {
+    console.error("Error handling operator response:", err.message);
+  }
+}
+
+// Phase 6: Gate approval via Slack reactions
+async function handleGateApproval(thread_ts, featureState) {
+  const flDir = featureState.impl_signal_tree?.featureLead;
+  if (!flDir) return;
+
+  const channel = featureState.impl_channel || PLANNING_CHANNEL;
+  await postToThread(
+    channel,
+    null,
+    `*[Pipeline]* Gate approved! Feature Lead will advance teams to next phase.`
+  );
+
+  // Write approval to Feature Lead's .user-message
+  fs.writeFileSync(
+    path.join(flDir, ".user-message"),
+    "GATE APPROVED. Advance all teams to the next phase."
+  );
+
+  featureState.gate_evidence_ts = null;
+  saveState();
+}
+
+async function handleGateRejection(thread_ts, featureState, reason) {
+  const flDir = featureState.impl_signal_tree?.featureLead;
+  if (!flDir) return;
+
+  const channel = featureState.impl_channel || PLANNING_CHANNEL;
+  await postToThread(
+    channel,
+    null,
+    `*[Pipeline]* Gate rejected. Feature Lead will re-dispatch with feedback.`
+  );
+
+  // Write rejection to Feature Lead's .user-message
+  fs.writeFileSync(
+    path.join(flDir, ".user-message"),
+    `GATE REJECTED: ${reason || "Please revise and resubmit."}`
+  );
+
+  featureState.gate_evidence_ts = null;
+  saveState();
+}
+
+// Phase 7: Feature completion
+async function handleFeatureComplete(filePath, slug, thread_ts) {
+  try {
+    const featureState = features[thread_ts];
+    if (!featureState) return;
+
+    const implChannel = featureState.impl_channel;
+
+    // Post summary to impl channel
+    if (implChannel) {
+      await web.chat.postMessage({
+        channel: implChannel,
+        text: `*[Pipeline]* Feature *${slug}* is complete! All gates passed. :tada:`,
+      });
+    }
+
+    // Post broadcast to #planning thread
+    await postToThread(
+      PLANNING_CHANNEL,
+      thread_ts,
+      `*[Pipeline]* Feature complete: *${slug}* :tada:\nAll gates approved and merged.`
+    );
+
+    // Also broadcast to channel
+    await web.chat.postMessage({
+      channel: PLANNING_CHANNEL,
+      thread_ts,
+      reply_broadcast: true,
+      text: `*Feature complete: ${slug}* :tada:`,
+    });
+
+    // Archive feature state
+    featureState.active_role = "complete";
+    featureState.completed_at = new Date().toISOString();
+    saveState();
+
+    // Kill all impl processes for this feature
+    killImplProcesses(slug);
+
+    console.log(`Feature ${slug} complete`);
+  } catch (err) {
+    console.error("Error handling feature complete:", err.message);
+  }
+}
+
+// Phase 8: Handover & context recovery
+async function handleNeedsRestart(filePath, slug, thread_ts) {
+  try {
+    const dir = path.dirname(filePath);
+    const featureState = features[thread_ts];
+    if (!featureState) return;
+
+    // Determine which agent needs restart by matching dir to signal tree
+    const tree = featureState.impl_signal_tree;
+    if (!tree) return;
+
+    let agentKey = null;
+    let agentLabel = null;
+    let runnerScript = null;
+    let runnerArgs = [];
+    let runnerCwd = null;
+    let runnerSignalDir = dir;
+
+    if (tree.featureLead === dir) {
+      agentKey = `fl-${slug}`;
+      agentLabel = "Feature Lead";
+      runnerScript = path.join(SCRIPTS_DIR, "run-feature-lead.sh");
+      const numTeams = Object.keys(tree.teams).length || 2;
+      runnerArgs = [slug, String(numTeams), "dynamic", "--slack"];
+      runnerCwd = IRIAI_TEAM_DIR;
+    } else if (tree.operator === dir) {
+      agentKey = `op-${slug}`;
+      agentLabel = "Operator";
+      runnerScript = path.join(SCRIPTS_DIR, "run-operator.sh");
+      runnerArgs = [slug, "--slack"];
+      runnerCwd = IRIAI_TEAM_DIR;
+    } else {
+      for (const [teamNum, team] of Object.entries(tree.teams)) {
+        if (team.orchestrator === dir) {
+          agentKey = `team-${slug}-${teamNum}`;
+          agentLabel = `Team ${teamNum} Orchestrator`;
+          runnerScript = path.join(SCRIPTS_DIR, "run-team.sh");
+          runnerArgs = [teamNum, "dynamic", slug, "--slack"];
+          runnerCwd = IRIAI_TEAM_DIR;
+          break;
+        }
+        for (const [role, roleDir] of Object.entries(team.roles)) {
+          if (roleDir === dir) {
+            agentKey = `role-${slug}-${teamNum}-${role}`;
+            agentLabel = `Team ${teamNum} ${role}`;
+            runnerScript = path.join(SCRIPTS_DIR, "run-role.sh");
+            const worktreeDir = path.join(
+              process.env.HOME, "src/iriai/.features", slug
+            );
+            const cwd = fs.existsSync(worktreeDir) ? worktreeDir : IRIAI_TEAM_DIR;
+            runnerArgs = [role, "opus", "--signal-dir", roleDir, "--cwd", cwd, "--slack"];
+            runnerCwd = cwd;
+            break;
+          }
+        }
+        if (agentKey) break;
+      }
+    }
+
+    if (!agentKey || !runnerScript) {
+      console.warn(`Could not identify agent for .needs-restart at ${dir}`);
+      fs.unlinkSync(filePath);
+      return;
+    }
+
+    // Read handover context
+    const handoverPath = path.join(dir, ".handover");
+    let handoverContent = "";
+    if (fs.existsSync(handoverPath)) {
+      handoverContent = fs.readFileSync(handoverPath, "utf-8");
+    }
+
+    // Kill the old process
+    if (implProcesses[agentKey]) {
+      try { process.kill(-implProcesses[agentKey], "SIGTERM"); } catch { /* gone */ }
+      delete implProcesses[agentKey];
+    }
+
+    // Clean up signal files
+    fs.unlinkSync(filePath);
+    if (fs.existsSync(handoverPath)) fs.unlinkSync(handoverPath);
+
+    // Post to impl channel
+    const channel = featureState.impl_channel || PLANNING_CHANNEL;
+    await web.chat.postMessage({
+      channel,
+      text: `*[Pipeline]* ${agentLabel} restarting (context limit). Work preserved.`,
+    });
+
+    // Respawn the runner (the runner script handles handover context internally
+    // via .handover files, or the Feature Lead's FEATURE-STATUS.md)
+    spawnImplRunner(agentKey, runnerScript, runnerArgs, runnerCwd, runnerSignalDir, {
+      IMPL_SIGNAL_BASE: IMPL_BASE,
+    });
+
+    console.log(`Restarted ${agentLabel} after context handover`);
+  } catch (err) {
+    console.error("Error handling needs-restart:", err.message);
+  }
+}
+
+// Spawn an implementation runner process (detached — fire and forget)
+function spawnImplRunner(key, script, args, cwd, signalDir, extraEnv) {
+  // Kill existing process if any
+  if (implProcesses[key]) {
+    try { process.kill(-implProcesses[key], "SIGTERM"); } catch { /* gone */ }
+    delete implProcesses[key];
+  }
+
+  const child = spawn("bash", [script, ...args], {
+    cwd,
+    env: { ...process.env, ...extraEnv },
+    detached: true,
+    stdio: "ignore",
+  });
+  child.unref();
+
+  implProcesses[key] = child.pid;
+  console.log(`Spawned ${key} (pid ${child.pid})`);
+  return child.pid;
+}
+
+// Kill all impl processes for a feature
+function killImplProcesses(slug) {
+  for (const [key, pid] of Object.entries(implProcesses)) {
+    if (key.includes(slug)) {
+      try { process.kill(-pid, "SIGTERM"); } catch { /* gone */ }
+      delete implProcesses[key];
+    }
+  }
+}
+
+// Phase 5: Launch implementation — spawn all runners after launch-feature.sh
+function launchImplRunners(slug, thread_ts) {
+  const tree = discoverImplSignalTree(slug);
+  const featureState = features[thread_ts];
+  if (!featureState) return;
+  featureState.impl_signal_tree = tree;
+  saveState();
+
+  const numTeams = Object.keys(tree.teams).length || 2;
+  const worktreeDir = path.join(process.env.HOME, "src/iriai/.features", slug);
+  const featureCwd = fs.existsSync(worktreeDir) ? worktreeDir : IRIAI_TEAM_DIR;
+
+  // Spawn Feature Lead
+  if (tree.featureLead) {
+    spawnImplRunner(
+      `fl-${slug}`,
+      path.join(SCRIPTS_DIR, "run-feature-lead.sh"),
+      [slug, String(numTeams), "dynamic", "--slack"],
+      IRIAI_TEAM_DIR,
+      tree.featureLead,
+      { IMPL_SIGNAL_BASE: IMPL_BASE }
+    );
+  }
+
+  // Spawn Operator (user-facing responder)
+  if (tree.operator) {
+    spawnImplRunner(
+      `op-${slug}`,
+      path.join(SCRIPTS_DIR, "run-operator.sh"),
+      [slug, "--slack"],
+      IRIAI_TEAM_DIR,
+      tree.operator,
+      { IMPL_SIGNAL_BASE: IMPL_BASE }
+    );
+  }
+
+  // Spawn team orchestrators and role runners
+  for (const [teamNum, team] of Object.entries(tree.teams)) {
+    if (team.orchestrator) {
+      spawnImplRunner(
+        `team-${slug}-${teamNum}`,
+        path.join(SCRIPTS_DIR, "run-team.sh"),
+        [teamNum, "dynamic", slug, "--slack"],
+        IRIAI_TEAM_DIR,
+        team.orchestrator,
+        { IMPL_SIGNAL_BASE: IMPL_BASE }
+      );
+    }
+
+    for (const [role, roleDir] of Object.entries(team.roles)) {
+      spawnImplRunner(
+        `role-${slug}-${teamNum}-${role}`,
+        path.join(SCRIPTS_DIR, "run-role.sh"),
+        [role, "opus", "--signal-dir", roleDir, "--cwd", featureCwd, "--slack"],
+        featureCwd,
+        roleDir,
+        { IMPL_SIGNAL_BASE: IMPL_BASE }
+      );
+    }
+  }
+
+  // Spawn feature-review runners (code-reviewer, integration-tester, security-auditor)
+  if (tree.featureReview) {
+    for (const [role, roleDir] of Object.entries(tree.featureReview)) {
+      spawnImplRunner(
+        `review-${slug}-${role}`,
+        path.join(SCRIPTS_DIR, "run-role.sh"),
+        [role, "opus", "--signal-dir", roleDir, "--cwd", featureCwd, "--slack"],
+        featureCwd,
+        roleDir,
+        { IMPL_SIGNAL_BASE: IMPL_BASE }
+      );
+    }
+  }
+
+  console.log(`Launched all impl runners for ${slug}: FL + operator + ${numTeams} teams + feature-review`);
+}
+
+// Process any existing impl signals on startup/recovery
+async function processExistingImplSignals() {
+  for (const [thread_ts, featureState] of Object.entries(features)) {
+    if (featureState.active_role !== "impl") continue;
+
+    const slug = featureState.feature_slug;
+    console.log(`Recovering impl watchers for active feature: ${slug}`);
+
+    // Re-establish watchers
+    watchImplSignals(slug, thread_ts);
+
+    // Check for unprocessed signals
+    const tree = featureState.impl_signal_tree;
+    if (!tree?.featureLead) continue;
+
+    const flDir = tree.featureLead;
+    const responsePath = path.join(flDir, ".agent-response");
+    if (fs.existsSync(responsePath)) {
+      console.log(`Found unprocessed .agent-response for impl Feature Lead`);
+      await handleImplAgentResponse(responsePath, slug, thread_ts);
+    }
+
+    if (tree.operator) {
+      const opResponsePath = path.join(tree.operator, ".agent-response");
+      if (fs.existsSync(opResponsePath)) {
+        console.log(`Found unprocessed .agent-response for Operator`);
+        await handleOperatorResponse(opResponsePath, slug, thread_ts);
+      }
+    }
+
+    const completePath = path.join(flDir, ".feature-complete");
+    if (fs.existsSync(completePath)) {
+      console.log(`Found unprocessed .feature-complete for ${slug}`);
+      await handleFeatureComplete(completePath, slug, thread_ts);
+    }
+  }
+}
+
+// ─── Dispatching ─────────────────────────────────────────────────────────────
+
+function dispatchToRole(role, featureSlug, thread_ts) {
+  const signalDir = ROLE_DIRS[role];
+  ensureDir(signalDir);
+
+  // Read existing task content if the planning lead already wrote one
+  // Otherwise create a task header for Slack mode
+  const taskHeader = [
+    "SLACK_MODE=true",
+    `FEATURE_SLUG=${featureSlug}`,
+    `SIGNAL_DIR=${signalDir}`,
+    `THREAD_TS=${thread_ts}`,
+    "---",
+  ].join("\n");
+
+  // Check if there's an existing .task from the planning lead
+  const taskPath = path.join(signalDir, ".task");
+  let existingTask = "";
+  if (fs.existsSync(taskPath)) {
+    existingTask = fs.readFileSync(taskPath, "utf-8");
+  }
+
+  // Write task with Slack mode header prepended
+  const taskContent = existingTask
+    ? `${taskHeader}\n${existingTask}`
+    : `${taskHeader}\nStart the ${ROLE_LABELS[role]} phase for feature: ${featureSlug}`;
+
+  fs.writeFileSync(taskPath, taskContent);
+
+  // Kill any existing runner for this role before spawning a new one
+  if (runningRoles[role]) {
+    console.log(`Killing previous ${role} runner (pid ${runningRoles[role]})`);
+    try { process.kill(-runningRoles[role], "SIGTERM"); } catch { /* gone */ }
+    delete runningRoles[role];
+  }
+
+  // Launch the role runner in Slack mode (detached)
+  const script = path.join(SCRIPTS_DIR, "run-planning-role.sh");
+  if (fs.existsSync(script)) {
+    const child = spawn("bash", [script, role, "--slack"], {
+      cwd: signalDir,
+      env: { ...process.env, PLANNING_SIGNAL_BASE: PLANNING_BASE },
+      detached: true,
+      stdio: "ignore",
+    });
+    child.unref();
+
+    runningRoles[role] = child.pid;
+    console.log(`Dispatched ${role} in Slack mode (pid ${child.pid})`);
+  }
+}
+
+// ─── Plan Approval ───────────────────────────────────────────────────────────
+
+async function postPlanForApproval(thread_ts, featureState) {
+  const slug = featureState.feature_slug;
+  const branch = `feature/${slug}`;
+
+  // Upload all three artifacts as file attachments in the thread
+  const prdPath = findArtifact("prd");
+  const designPath = findArtifact("design-decisions");
+  const planPath = findArtifact("implementation-plan");
+
+  if (prdPath) await uploadArtifact(PLANNING_CHANNEL, thread_ts, prdPath, "PRD");
+  if (designPath) await uploadArtifact(PLANNING_CHANNEL, thread_ts, designPath, "Design Decisions");
+  if (planPath) await uploadArtifact(PLANNING_CHANNEL, thread_ts, planPath, "Implementation Plan");
+
+  // Post the approval prompt (thread-only)
+  const result = await web.chat.postMessage({
+    channel: PLANNING_CHANNEL,
+    thread_ts,
+    text: `*[Pipeline]* Plan ready for approval.\n\nReact :white_check_mark: to approve or :x: to reject.\nOr reply with "approved" / "rejected: <reason>".`,
+  });
+
+  featureState.plan_summary_ts = result.ts;
+
+  // Broadcast a single summary to the channel (Also send to channel)
+  const artifactList = [prdPath, designPath, planPath]
+    .filter(Boolean)
+    .map((p) => path.basename(p))
+    .join(", ");
+
+  await web.chat.postMessage({
+    channel: PLANNING_CHANNEL,
+    thread_ts,
+    reply_broadcast: true,
+    text: [
+      `*Planning complete: ${slug}*`,
+      ``,
+      `Branch: \`${branch}\``,
+      `Artifacts: ${artifactList || "none"}`,
+      ``,
+      `React :white_check_mark: to approve or :x: to reject (in thread).`,
+    ].join("\n"),
+  });
+
+  featureState.active_role = null; // Waiting for approval
+  saveState();
+}
+
+async function handleApproval(thread_ts, featureState) {
+  const slug = featureState.feature_slug;
+
+  await postToThread(
+    PLANNING_CHANNEL,
+    thread_ts,
+    `*[Pipeline]* Plan approved! Creating implementation channel and launching feature...`
+  );
+
+  // Create #impl-<slug> channel
+  try {
+    const result = await web.conversations.create({
+      name: `impl-${slug}`.slice(0, 80),
+    });
+    featureState.impl_channel = result.channel.id;
+    saveState();
+
+    await web.chat.postMessage({
+      channel: result.channel.id,
+      text: `Implementation channel for feature: *${slug}*\nPlanning thread: https://slack.com/archives/${PLANNING_CHANNEL}/p${thread_ts.replace(".", "")}`,
+    });
+  } catch (err) {
+    // Channel may already exist
+    if (err.data?.error === "name_taken") {
+      try {
+        const list = await web.conversations.list({ types: "public_channel", limit: 200 });
+        const existing = list.channels.find(
+          (c) => c.name === `impl-${slug}`.slice(0, 80)
+        );
+        if (existing) featureState.impl_channel = existing.id;
+      } catch {
+        // Continue without impl channel
+      }
+    }
+    console.warn("Could not create impl channel:", err.message);
+  }
+
+  // Auto-detect repos from the implementation plan and ask for confirmation.
+  const detectedRepos = detectReposFromPlan();
+
+  featureState.pending_repos = detectedRepos;
+  featureState.awaiting_repo_confirm = true;
+  saveState();
+
+  const repoList = detectedRepos.length > 0
+    ? detectedRepos.map((r) => `  - \`${r}\``).join("\n")
+    : "  _(none detected — check implementation plan)_";
+
+  const implChannelLink = featureState.impl_channel
+    ? `*Impl channel:* <#${featureState.impl_channel}>`
+    : "";
+
+  await postToThread(
+    PLANNING_CHANNEL,
+    thread_ts,
+    [
+      `*[Pipeline]* Ready to launch implementation.`,
+      ``,
+      `*Feature:* ${slug}`,
+      `*Branch:* \`feature/${slug}\``,
+      implChannelLink,
+      `*Repos affected:*`,
+      repoList,
+      ``,
+      `Reply *"go"* to create branches and start implementation.`,
+    ].filter(Boolean).join("\n")
+  );
+}
+
+async function handleRejection(thread_ts, featureState, reason) {
+  await postToThread(
+    PLANNING_CHANNEL,
+    thread_ts,
+    `*[Pipeline]* Plan rejected. Re-dispatching Architect with feedback...`
+  );
+
+  featureState.active_role = "architect";
+  saveState();
+
+  // Write rejection feedback as .user-message to architect
+  const archDir = ROLE_DIRS.architect;
+  ensureDir(archDir);
+  fs.writeFileSync(
+    path.join(archDir, ".user-message"),
+    `REVISION REQUESTED: ${reason || "Plan rejected. Please revise."}`
+  );
+
+  dispatchToRole("architect", featureState.feature_slug, thread_ts);
+}
+
+// ─── Message Handling ────────────────────────────────────────────────────────
+
+socketClient.on("message", async ({ event, ack }) => {
+  await ack();
+
+  console.log(`[MSG] channel=${event.channel} user=${event.user} thread_ts=${event.thread_ts || "none"} text="${(event.text || "").slice(0, 80)}" subtype=${event.subtype || "none"}`);
+
+  // Ignore bot messages
+  if (event.bot_id || event.subtype === "bot_message") return;
+
+  const text = (event.text || "").trim();
+  const channel = event.channel;
+  const thread_ts = event.thread_ts || event.ts;
+  const isThreadReply = !!event.thread_ts;
+
+  // ── Feature detection: top-level [FEATURE] messages in #planning ──
+  if (
+    channel === PLANNING_CHANNEL &&
+    !isThreadReply &&
+    text.toUpperCase().startsWith("[FEATURE]")
+  ) {
+    const featureDesc = text.replace(/^\[FEATURE\]\s*/i, "").trim();
+    const slug = slugify(featureDesc);
+
+    // Create thread
+    const reply = await web.chat.postMessage({
+      channel: PLANNING_CHANNEL,
+      thread_ts: event.ts,
+      text: `*[Pipeline]* Starting planning pipeline for: *${slug}*\nPhase 1: Product Manager interview`,
+    });
+
+    features[event.ts] = {
+      feature_slug: slug,
+      active_role: "pm",
+      signal_dir: ROLE_DIRS.pm,
+      plan_summary_ts: null,
+      impl_channel: null,
+    };
+    saveState();
+
+    // Dispatch PM
+    dispatchToRole("pm", slug, event.ts);
+    return;
+  }
+
+  // ── Thread replies: route to active role ──
+  if (isThreadReply && features[thread_ts]) {
+    const featureState = features[thread_ts];
+    const lower = text.toLowerCase();
+
+    // ── Repo confirmation after approval ──
+    if (featureState.awaiting_repo_confirm) {
+      if (lower !== "go" && lower !== "yes" && lower !== "y") {
+        return; // Ignore non-confirmation messages
+      }
+
+      const repos = featureState.pending_repos || [];
+
+      featureState.awaiting_repo_confirm = false;
+      featureState.pending_repos = null;
+      saveState();
+
+      // Run planning-complete.sh with the slug and repos
+      try {
+        if (repos.length > 0) {
+          await postToThread(
+            PLANNING_CHANNEL,
+            thread_ts,
+            `*[Pipeline]* Creating \`feature/${featureState.feature_slug}\` branches in ${repos.length} repo(s)...`
+          );
+
+          const completeScript = path.join(SCRIPTS_DIR, "planning-complete.sh");
+          if (fs.existsSync(completeScript)) {
+            execSync(
+              `bash "${completeScript}" "${featureState.feature_slug}" ${repos.map((r) => `"${r}"`).join(" ")}`,
+              { cwd: IRIAI_TEAM_DIR, stdio: "pipe", timeout: 120000 }
+            );
+          }
+          await postToThread(
+            PLANNING_CHANNEL,
+            thread_ts,
+            `*[Pipeline]* Feature branches created. Launching implementation...`
+          );
+        } else {
+          await postToThread(
+            PLANNING_CHANNEL,
+            thread_ts,
+            `*[Pipeline]* No repos configured — skipping branch creation. Launching implementation...`
+          );
+        }
+
+        // Run launch-feature.sh synchronously (creates dirs, worktrees, exits in Slack mode)
+        const launchScript = path.join(SCRIPTS_DIR, "launch-feature.sh");
+        if (fs.existsSync(launchScript)) {
+          try {
+            execSync(
+              `bash "${launchScript}" "${featureState.feature_slug}"`,
+              {
+                cwd: IRIAI_TEAM_DIR,
+                stdio: "pipe",
+                timeout: 300000,
+                env: {
+                  ...process.env,
+                  PLANNING_SIGNAL_BASE: PLANNING_BASE,
+                  IMPL_SIGNAL_BASE: IMPL_BASE,
+                  SLACK_MODE: "true",
+                  FEATURE_SLUG: featureState.feature_slug,
+                  IMPL_CHANNEL: featureState.impl_channel || "",
+                },
+              }
+            );
+          } catch (launchErr) {
+            console.error("launch-feature.sh failed:", launchErr.message);
+            const stderr = launchErr.stderr ? launchErr.stderr.toString().slice(-500) : launchErr.message;
+            await postToThread(
+              PLANNING_CHANNEL,
+              thread_ts,
+              `*[Pipeline]* Error setting up implementation:\n\`\`\`${stderr}\`\`\``
+            );
+            featureState.awaiting_repo_confirm = true;
+            saveState();
+            return;
+          }
+
+          // Discover the signal tree created by launch-feature.sh
+          watchImplSignals(featureState.feature_slug, thread_ts);
+
+          // Spawn all runner processes (Feature Lead, orchestrators, roles)
+          launchImplRunners(featureState.feature_slug, thread_ts);
+
+          const implLink = featureState.impl_channel
+            ? ` Follow progress in <#${featureState.impl_channel}>.`
+            : "";
+          await postToThread(
+            PLANNING_CHANNEL,
+            thread_ts,
+            `*[Pipeline]* Implementation launched for \`feature/${featureState.feature_slug}\`.${implLink}`
+          );
+        }
+
+        featureState.active_role = "impl";
+        saveState();
+      } catch (err) {
+        const stderr = err.stderr ? err.stderr.toString().slice(-500) : err.message;
+        await postToThread(
+          PLANNING_CHANNEL,
+          thread_ts,
+          `*[Pipeline]* Error creating branches:\n\`\`\`${stderr}\`\`\`\nYou can retry by replying with the repo list again.`
+        );
+        featureState.awaiting_repo_confirm = true;
+        saveState();
+      }
+      return;
+    }
+
+    // Check for approval/rejection text
+    if (
+      featureState.plan_summary_ts &&
+      featureState.active_role === null &&
+      !featureState.awaiting_repo_confirm
+    ) {
+      if (
+        lower === "approved" ||
+        lower === "lgtm" ||
+        lower.startsWith("approve")
+      ) {
+        await handleApproval(thread_ts, featureState);
+        return;
+      }
+      if (
+        lower.startsWith("reject") ||
+        lower === "no" ||
+        lower === "nope" ||
+        lower.startsWith("redo") ||
+        lower.startsWith("revise")
+      ) {
+        const reason = text.replace(/^(rejected?|no|nope|redo|revise):?\s*/i, "").trim();
+        await handleRejection(thread_ts, featureState, reason || "Plan rejected");
+        return;
+      }
+    }
+
+    // Route to specific role via @mention, or fall back to active role
+    const mentionedRole = parseRole(text);
+    const targetRole = mentionedRole || featureState.active_role;
+
+    if (targetRole && ROLE_DIRS[targetRole]) {
+      const signalDir = ROLE_DIRS[targetRole];
+      ensureDir(signalDir);
+
+      // Strip the @mention from the message before writing
+      const cleanText = text
+        .replace(/@(pm|designer|architect|plan-compiler|compiler|lead)\b/gi, "")
+        .trim();
+
+      fs.writeFileSync(path.join(signalDir, ".user-message"), cleanText);
+
+      // Add :eyes: to show the agent is processing
+      await addReaction(channel, event.ts, "eyes");
+      pendingUserMessages[thread_ts] = event.ts;
+    }
+    return;
+  }
+
+  // ── Messages in impl channels: route to Operator (with FL fallback) ──
+  const implFeature = Object.entries(features).find(
+    ([, f]) => f.impl_channel === channel
+  );
+  if (implFeature) {
+    const [implThread, featureState] = implFeature;
+
+    const lower = text.toLowerCase();
+
+    // Check for gate approval/rejection text in impl channel
+    if (featureState.gate_evidence_ts) {
+      if (lower === "approved" || lower === "lgtm" || lower.startsWith("approve")) {
+        await handleGateApproval(implThread, featureState);
+        return;
+      }
+      if (lower.startsWith("reject")) {
+        const reason = text.replace(/^rejected?:?\s*/i, "");
+        await handleGateRejection(implThread, featureState, reason);
+        return;
+      }
+    }
+
+    // Route to operator (fast responder) with FL fallback
+    const targetDir = featureState.impl_signal_tree?.operator || featureState.impl_signal_tree?.featureLead || ROLE_DIRS.lead;
+    ensureDir(targetDir);
+    fs.writeFileSync(path.join(targetDir, ".user-message"), text);
+
+    // Add :eyes: to show the agent is processing
+    await addReaction(channel, event.ts, "eyes");
+    pendingUserMessages[implThread] = event.ts;
+  }
+});
+
+// ── Reaction handling for plan approval and gate approval ──
+socketClient.on("reaction_added", async ({ event, ack }) => {
+  await ack();
+
+  const { reaction, item } = event;
+  console.log(`[REACTION] ${reaction} on ${item.type} ts=${item.ts} channel=${item.channel} user=${event.user} botUserId=${botUserId}`);
+
+  // Ignore our own reactions (e.g., approval hint checkmarks we add to gate evidence)
+  if (event.user === botUserId) {
+    console.log(`[REACTION] Ignoring self-reaction from bot`);
+    return;
+  }
+
+  if (item.type !== "message") return;
+
+  const messageTs = item.ts;
+
+  // Check for plan approval reaction — match on the approval prompt message,
+  // the thread parent message, or any message in the thread while awaiting approval.
+  const planFeature = Object.entries(features).find(
+    ([thread_ts, f]) =>
+      f.plan_summary_ts &&
+      f.active_role === null &&
+      !f.awaiting_repo_confirm &&
+      (f.plan_summary_ts === messageTs || thread_ts === messageTs)
+  );
+  if (planFeature) {
+    const [featureThread, featureState] = planFeature;
+    if (reaction === "white_check_mark" || reaction === "+1") {
+      await handleApproval(featureThread, featureState);
+    } else if (reaction === "x" || reaction === "-1") {
+      await handleRejection(featureThread, featureState, "Rejected via reaction");
+    }
+    return;
+  }
+
+  // Check for gate approval reaction (Phase 6)
+  const gateFeature = Object.entries(features).find(
+    ([, f]) => f.gate_evidence_ts === messageTs
+  );
+  if (gateFeature) {
+    const [featureThread, featureState] = gateFeature;
+    if (reaction === "white_check_mark" || reaction === "+1") {
+      await handleGateApproval(featureThread, featureState);
+    } else if (reaction === "x" || reaction === "-1") {
+      await handleGateRejection(featureThread, featureState, "Rejected via reaction");
+    }
+  }
+});
+
+// ─── Startup Recovery ────────────────────────────────────────────────────────
+
+async function processExistingSignals() {
+  // On restart, check for .done / .agent-response files that were written
+  // while the bridge was down. chokidar ignoreInitial:true won't catch these.
+  for (const [role, dir] of Object.entries(ROLE_DIRS)) {
+    const donePath = path.join(dir, ".done");
+    if (fs.existsSync(donePath)) {
+      console.log(`Found unprocessed .done for ${role}, processing...`);
+      await handleDoneSignal(donePath);
+    }
+
+    const responsePath = path.join(dir, ".agent-response");
+    if (fs.existsSync(responsePath)) {
+      console.log(`Found unprocessed .agent-response for ${role}, processing...`);
+      await handleAgentResponse(responsePath);
+    }
+
+    const questionPath = path.join(dir, ".question");
+    if (fs.existsSync(questionPath)) {
+      console.log(`Found unprocessed .question for ${role}, processing...`);
+      await handleQuestionSignal(questionPath);
+    }
+  }
+}
+
+// ─── Startup ─────────────────────────────────────────────────────────────────
+
+async function start() {
+  console.log("Starting Iriai Slack Bridge...");
+
+  // Identify ourselves so we can filter our own reactions
+  const authResult = await web.auth.test();
+  botUserId = authResult.user_id;
+  console.log(`Bot user ID: ${botUserId}`);
+
+  // Ensure signal dirs exist
+  for (const dir of Object.values(ROLE_DIRS)) {
+    ensureDir(dir);
+  }
+
+  // Load persisted state for crash recovery
+  loadState();
+
+  // Start file watchers
+  watchAgentResponses();
+
+  // Connect Socket Mode
+  await socketClient.start();
+  console.log("Socket Mode connected. Watching #planning for [FEATURE] messages.");
+
+  // Wait for connection to stabilize before processing leftover signals
+  await new Promise((resolve) => setTimeout(resolve, 3000));
+
+  // Check for unprocessed signals left over from before restart
+  await processExistingSignals();
+
+  // Recover impl watchers for any active implementation features
+  await processExistingImplSignals();
+}
+
+// Handle Socket Mode disconnects gracefully
+socketClient.on("disconnect", () => {
+  console.warn("Socket Mode disconnected. Will attempt reconnect...");
+});
+
+// Catch unhandled rejections so the process doesn't crash on transient Slack errors
+process.on("unhandledRejection", (err) => {
+  console.error("Unhandled rejection (non-fatal):", err.message || err);
+});
+
+start().catch((err) => {
+  console.error("Fatal:", err);
+  process.exit(1);
+});