iriai-build 0.1.0

package/v3/orchestrator.js

@@ -0,0 +1,2886 @@
+// orchestrator.js — Feature lifecycle + agent dispatch state machines.
+// The core brain of bridge v3. Replaces bridge-v2.js state machines + signal handlers.
+// State lives in SQLite — no in-memory state machines.
+
+import fs from "node:fs";
+import path from "node:path";
+import { execSync, spawn as cpSpawn } from "node:child_process";
+import * as db from "./db.js";
+import * as queries from "./queries.js";
+import { AgentSupervisor } from "./agent-supervisor.js";
+import AgentProcess from "../lib/agent-process.js";
+import { FileIO } from "./file-io.js";
+import { invokeOperator, invokeOperatorRelay, parseOperatorResponse } from "./operator.js";
+import {
+  buildPlanningRolePrompt, buildArtifactSummarizerPrompt, buildRolePrompt, buildOrchestratorPrompt,
+  buildFeatureLeadInitPrompt, buildFeatureLeadRefreshPrompt, buildFeatureLeadTriggerPrompt,
+} from "./prompt-builder.js";
+import {
+  IMPL_BASE, IRIAI_TEAM_DIR, SCRIPTS_DIR,
+  V3_ROLES_DIR, PLANNING_ROLES, PLANNING_ROLE_LABELS,
+  ROLE_LABELS, PIPELINE_ORDER, SIGNAL,
+  STALE_SCAN_INTERVAL_MS, OPERATOR_RELAY_TIMEOUT_MS,
+  MAX_PLANNING_RETRIES, MAX_FL_RETRIES, MAX_FL_INIT_RETRIES,
+  MAX_ROLE_RETRIES, MAX_ORCH_RETRIES, MAX_OPERATOR_RETRIES,
+  FL_CONTEXT_EXHAUST_MS, FEATURE_REVIEW_ROLES,
+  ARTIFACT_SUMMARY_THRESHOLD_KB, ARTIFACT_SUMMARY_FILE,
+  SUMMARIZER_TIMEOUT_MS, SUMMARIZER_MODEL,
+} from "./constants.js";
+import {
+  readSignal, writeSignal, ensureDir, detectReposFromPlan, scaffoldNewRepo, slugify,
+  findArtifact,
+} from "./helpers.js";
+import { formatAnnotationsAsFeedback } from "./review-sessions.js";
+import { compilePlanReviewHtml } from "./plan-compiler.js";
+
+export class Orchestrator {
+  constructor({ adapter, reviewSessions = null }) {
+    this.adapter = adapter;
+    this.reviewSessions = reviewSessions;
+    this.supervisor = new AgentSupervisor();
+    this.fileIO = new FileIO();
+
+    // Per-feature signal trees (discovered on launch)
+    this._signalTrees = {};
+
+    // Operator relay queue processing state (per feature)
+    this._relayProcessing = {};
+    // Pending relay promises: relayQueueId → { resolve, timer }
+    this._relayWaiters = {};
+    // Deferred decisions: featureId → { decision, featureId } — posted after Operator relay completes
+    this._deferredDecisions = {};
+
+    this._staleScanTimer = null;
+
+    // When true, handlePlanApproval will NOT auto-launch implementation.
+    // The CLI sets this so it can prompt "Continue to implementation?" first.
+    this.deferImplLaunch = false;
+
+    this._setupFileIOHandlers();
+    this._setupSupervisorHandlers();
+    this.supervisor.startHealthMonitor();
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // FEATURE INITIALIZATION (at [FEATURE] detection)
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Initialize a feature from [FEATURE] detection: create per-feature dirs,
+   * feature channel, operator record, and start planning pipeline.
+   */
+  async initializeFeature(slug, messageTs, userId) {
+    const featureDir = path.join(IMPL_BASE, "features", slug);
+
+    // 1. Create directories
+    const operatorDir = path.join(featureDir, "operator");
+    const plansDir = path.join(featureDir, "plans");
+    ensureDir(operatorDir);
+    ensureDir(plansDir);
+
+    const planningTree = {};
+    for (const role of PLANNING_ROLES) {
+      const roleDir = path.join(featureDir, "planning", role);
+      ensureDir(roleDir);
+      planningTree[role] = roleDir;
+    }
+
+    // 2. Symlink CLAUDE.md from v3/roles/ into planning + operator dirs
+    for (const role of PLANNING_ROLES) {
+      const src = path.join(V3_ROLES_DIR, role, "CLAUDE.md");
+      const dest = path.join(planningTree[role], "CLAUDE.md");
+      try { fs.unlinkSync(dest); } catch { /* ok */ }
+      fs.symlinkSync(src, dest);
+    }
+    const opSrc = path.join(V3_ROLES_DIR, "operator", "CLAUDE.md");
+    const opDest = path.join(operatorDir, "CLAUDE.md");
+    try { fs.unlinkSync(opDest); } catch { /* ok */ }
+    fs.symlinkSync(opSrc, opDest);
+
+    // 3. Create feature in SQLite
+    const feature = queries.createFeature({ slug, threadTs: messageTs, signalDir: featureDir });
+    queries.insertEvent(feature.id, "system", `user:${userId}`, `Feature requested: ${slug}`);
+
+    // 4. Create feature channel immediately
+    const channelId = await this.adapter.createFeatureChannel(feature.id, slug);
+    if (channelId) {
+      queries.updateFeatureChannel(feature.id, channelId);
+    }
+
+    // 5. Create Operator agent record (idle, ready for relay)
+    queries.createAgent({
+      featureId: feature.id,
+      agentType: "operator",
+      agentKey: `op-${slug}`,
+      roleName: "operator",
+      signalDir: operatorDir,
+      cwd: featureDir,
+      maxRetries: MAX_OPERATOR_RETRIES,
+    });
+
+    // 6. Post link in #planning thread
+    if (channelId) {
+      await this.adapter.postThreadMessage(feature.id,
+        `*[Pipeline]* Starting planning for *${slug}*. Implementation channel: <#${channelId}>`);
+      await this.adapter.postMessage(feature.id,
+        `*[Pipeline]* Planning pipeline started for feature: *${slug}*\nPhase 1: Product Manager interview`);
+    } else {
+      await this.adapter.postThreadMessage(feature.id,
+        `*[Pipeline]* Starting planning pipeline for: *${slug}*\nPhase 1: Product Manager interview`);
+    }
+
+    // 7. Cache signal tree with planning field
+    this._signalTrees[slug] = {
+      featureDir,
+      featureLead: null,
+      operator: operatorDir,
+      featureReview: {},
+      teams: {},
+      planning: planningTree,
+      plansDir,
+    };
+
+    // 8. Start watching per-feature planning + operator signals
+    this.fileIO.watchFeaturePlanningSignals(slug, planningTree, operatorDir);
+
+    // 9. Set active planning role and dispatch PM
+    queries.updateFeaturePlanningRole(feature.id, "pm");
+    this.dispatchPlanningRole(feature.id, "pm");
+
+    return feature;
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // PLANNING PIPELINE
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Dispatch a planning role agent (PM, Designer, Architect, Plan-Compiler).
+   */
+  dispatchPlanningRole(featureId, role, opts = {}) {
+    const feature = queries.getFeatureById(featureId);
+    if (!feature) return;
+
+    // Compute dirs from feature record instead of global ROLE_DIRS
+    const featureDir = feature.signal_dir;
+    const signalDir = path.join(featureDir, "planning", role);
+    const planDir = path.join(featureDir, "plans");
+    ensureDir(signalDir);
+    ensureDir(planDir);
+
+    // Use repos worktree dir as cwd if it exists, otherwise signal dir
+    const reposDir = path.join(process.env.HOME, "src/iriai/.features", feature.slug, "repos");
+    const roleCwd = fs.existsSync(reposDir) ? reposDir : signalDir;
+
+    const agentKey = `${role}-${feature.slug}`;
+
+    // Kill existing if any
+    this.supervisor.kill(agentKey);
+
+    // Clean up stale signal files from previous run so the file watcher
+    // doesn't immediately fire _handlePlanningDone before the agent starts.
+    for (const sig of [SIGNAL.DONE, SIGNAL.OUTPUT]) {
+      try { fs.unlinkSync(path.join(signalDir, sig)); } catch { /* ok */ }
+    }
+
+    // Create or update agent record
+    let agent = queries.getAgentByKey(agentKey);
+    const hasSession = agent?.started_at != null;
+    if (!agent) {
+      agent = queries.createAgent({
+        featureId,
+        agentType: "planning-role",
+        agentKey,
+        roleName: role,
+        signalDir,
+        cwd: roleCwd,
+        maxRetries: MAX_PLANNING_RETRIES,
+      });
+    } else {
+      queries.updateAgentStatus(agent.id, "idle");
+      queries.resetAgentRetry(agent.id);
+      this._syncAgentRetries(agent, MAX_PLANNING_RETRIES);
+    }
+
+    // Build task from any existing .task file in the signal dir
+    let task = "";
+    const taskFile = path.join(signalDir, SIGNAL.TASK);
+    if (fs.existsSync(taskFile)) {
+      task = fs.readFileSync(taskFile, "utf-8").trim();
+    }
+
+    // Check for pending .user-message (e.g. revision feedback) and inline it
+    const userMsgFile = path.join(signalDir, SIGNAL.USER_MESSAGE);
+    let revisionContext = "";
+    if (fs.existsSync(userMsgFile)) {
+      const msg = fs.readFileSync(userMsgFile, "utf-8").trim();
+      if (msg) {
+        revisionContext = `\n\n--- REVISION FEEDBACK ---\n${msg}\n--- END FEEDBACK ---\n\nYou are being re-dispatched after a phase review rejection. Address the feedback above. Read your previous output in $PLAN_DIR/ and revise it.`;
+      }
+      // Don't delete — the agent's poll loop will also pick it up as a belt-and-suspenders
+    }
+
+    // Add feature header with PLAN_DIR, FEATURE_DIR, REPOS_DIR
+    const taskHeader = [
+      `SLACK_MODE=true`,
+      `FEATURE_SLUG=${feature.slug}`,
+      `SIGNAL_DIR=${signalDir}`,
+      `PLAN_DIR=${planDir}`,
+      `FEATURE_DIR=${featureDir}`,
+      `REPOS_DIR=${reposDir}`,
+      `THREAD_TS=${feature.thread_ts}`,
+    ].join("\n");
+    const fullTask = task ? `${taskHeader}\n\n${task}${revisionContext}` : `${taskHeader}${revisionContext}`;
+
+    const prompt = buildPlanningRolePrompt({ task: fullTask, signalDir, featureSlug: feature.slug });
+
+    queries.updateFeaturePlanningRole(featureId, role);
+    queries.insertEvent(featureId, "agent-started", "bridge", `Planning role ${role} dispatched`);
+
+    // Use --continue if agent has a prior session and caller didn't explicitly set continue
+    const useContinue = opts.continue !== undefined ? opts.continue : hasSession;
+    this.supervisor.spawn(agent.id, prompt, { continue: useContinue });
+  }
+
+  /**
+   * Handle planning role completion — upload artifact + post review gate (or handle plan-compiler).
+   */
+  async _handlePlanningDone(slug, role, filePath) {
+    const dir = path.dirname(filePath);
+    const label = ROLE_LABELS[role] || role;
+
+    const feature = queries.getFeatureBySlug(slug);
+    if (!feature) return;
+
+    // Dedup guard: both file watcher (planning:done) and agent exit handler
+    // (_handlePlanningRoleExit) can call this for the same .done file.
+    // We use a synchronous in-memory lock + metadata check to prevent concurrent processing.
+    const dedupKey = `planningDone:${feature.id}:${role}`;
+    if (this._planningDoneLocks?.[dedupKey]) return;
+    const meta = queries.getFeatureMetadata(feature.id);
+    if (meta.awaiting_phase_review && meta.phase_review_role === role) return;
+    if (role === "plan-compiler" && feature.phase === "plan-approval") return;
+
+    // Acquire lock before any async work
+    if (!this._planningDoneLocks) this._planningDoneLocks = {};
+    this._planningDoneLocks[dedupKey] = true;
+
+    try {
+    // Read .output
+    const outputPath = path.join(dir, SIGNAL.OUTPUT);
+    let output = "";
+    if (fs.existsSync(outputPath)) {
+      output = fs.readFileSync(outputPath, "utf-8").trim();
+    }
+
+    queries.insertEvent(feature.id, "phase-transition", "bridge", `${label} complete`, { output });
+
+    // Clean up .done/.output after reading — output is already in memory.
+    try { fs.unlinkSync(filePath); } catch { /* ok */ }
+    if (fs.existsSync(outputPath)) try { fs.unlinkSync(outputPath); } catch { /* ok */ }
+
+    if (role === "plan-compiler") {
+      // Check PASS/FAIL
+      const isPassing = output && (output.startsWith("PASS") || output.startsWith("PASS_WITH_WARNINGS"));
+      if (!isPassing) {
+        // FAIL → re-dispatch architect (no user gate)
+        await this.adapter.postPipelineMessage(feature.id,
+          `Plan validation failed. Re-dispatching Architect.\n\n${output}`);
+        queries.updateFeaturePlanningRole(feature.id, "architect");
+        const archDir = path.join(feature.signal_dir, "planning", "architect");
+        ensureDir(archDir);
+        writeSignal(path.join(archDir, SIGNAL.USER_MESSAGE),
+          `REVISION REQUESTED: Plan compiler validation failed.\n\n${output}`);
+        this.dispatchPlanningRole(feature.id, "architect");
+      } else {
+        // PASS → final plan approval (uploads + buttons)
+        db.transaction(() => {
+          queries.updateFeaturePhase(feature.id, "plan-approval");
+          queries.updateFeaturePlanningRole(feature.id, null);
+        });
+        const planDir = path.join(feature.signal_dir, "plans");
+
+        // Upload artifacts (without decision buttons — those are deferred)
+        for (const art of [
+          { name: "PRD", pattern: "prd" },
+          { name: "Design Decisions", pattern: "design-decisions" },
+          { name: "Implementation Plan", pattern: "implementation-plan" },
+        ]) {
+          const artPath = findArtifact(art.pattern, planDir);
+          if (artPath) await this.adapter.uploadArtifact(feature.id, artPath, art.name);
+        }
+
+        // Start interactive plan review session (compiled tabbed HTML)
+        let reviewUrl = null;
+        if (this.reviewSessions) {
+          const compiledPath = compilePlanReviewHtml(planDir);
+          if (compiledPath) {
+            reviewUrl = await this.reviewSessions.startDocReview(
+              "plan-approval", compiledPath, "Plan Review", { featureId: feature.id }
+            );
+          }
+        }
+
+        const planDecision = {
+          id: "plan-approval",
+          title: "Plan ready for approval",
+          context: "All planning phases complete. Review the artifacts.",
+          options: [
+            { id: "approve", label: "Approve Plan", style: "primary" },
+            { id: "reject", label: "Reject Plan", style: "danger" },
+          ],
+          reviewUrl,
+
+        };
+
+        // Defer decision until after Operator relay completes
+        this._deferredDecisions[feature.id] = { decision: planDecision, featureId: feature.id };
+        this._notifyOperatorOfDecision(feature, planDecision);
+      }
+    } else {
+      // Non-final role → summary + artifact upload + Block Kit review gate (all sequential)
+      await this._requestPhaseReview(feature, role, output);
+    }
+
+    } finally {
+      // Release the dedup lock
+      delete this._planningDoneLocks[dedupKey];
+    }
+  }
+
+  /**
+   * Post phase summary, upload artifact, then post Block Kit approve/reject buttons.
+   * Everything is sequential to guarantee correct message ordering.
+   */
+  async _requestPhaseReview(feature, role, output) {
+    const planDir = path.join(feature.signal_dir, "plans");
+    const label = PLANNING_ROLE_LABELS[role] || role;
+
+    // Artifact definitions — used for review session targets and fallback uploads
+    const ARTIFACT_MAP = {
+      pm: [{ name: "PRD", pattern: "prd" }],
+      designer: [
+        { name: "Design Decisions", pattern: "design-decisions" },
+        { name: "UI Mockup", file: "mockup.html" },
+      ],
+      architect: [
+        { name: "Implementation Plan (plan.yaml)", file: "plan.yaml" },
+        { name: "Architecture Context", pattern: "context" },
+      ],
+    };
+
+    const artifacts = ARTIFACT_MAP[role] || [];
+
+    // Only upload raw artifacts if review sessions are NOT available
+    // (review sessions replace file uploads with interactive doc review URLs)
+    if (!this.reviewSessions) {
+      for (const artifact of artifacts) {
+        const artifactPath = artifact.file
+          ? (fs.existsSync(path.join(planDir, artifact.file)) ? path.join(planDir, artifact.file) : null)
+          : findArtifact(artifact.pattern, planDir);
+        if (artifactPath) {
+          await this.adapter.uploadArtifact(feature.id, artifactPath, artifact.name);
+        }
+      }
+    }
+    const artifact = artifacts[0]; // primary artifact for button text
+
+    const nextRole = PIPELINE_ORDER[PIPELINE_ORDER.indexOf(role) + 1];
+    const nextLabel = PLANNING_ROLE_LABELS[nextRole] || nextRole;
+    const decisionId = `phase-review-${feature.slug}-${role}`;
+
+    // Set awaiting_phase_review BEFORE postDecision so handleDecisionClick
+    // can find the feature when the user responds.
+    const meta = queries.getFeatureMetadata(feature.id);
+    meta.awaiting_phase_review = true;
+    meta.phase_review_role = role;
+    meta.phase_review_ts = decisionId;
+    queries.updateFeatureMetadata(feature.id, meta);
+
+    // For designer phase: detect mockup.html, serve it, inject URL into design-decisions.md
+    if (role === "designer" && this.reviewSessions) {
+      await this._ensureMockupSession(planDir, `${decisionId}-mockup`, feature.id);
+    }
+
+    // Start interactive review session for the primary artifact
+    let reviewUrl = null;
+    if (this.reviewSessions) {
+      const primaryArtifact = artifacts[0];
+      const primaryPath = primaryArtifact?.file
+        ? (fs.existsSync(path.join(planDir, primaryArtifact.file)) ? path.join(planDir, primaryArtifact.file) : null)
+        : findArtifact(primaryArtifact?.pattern, planDir);
+      if (primaryPath) {
+        reviewUrl = await this.reviewSessions.startDocReview(
+          decisionId, primaryPath, primaryArtifact.name, { featureId: feature.id }
+        );
+      }
+    }
+
+    const decision = {
+      id: decisionId,
+      title: `${label} phase complete — review the ${artifact?.name || "output"} above`,
+      context: `Approve to proceed to ${nextLabel}, or reject to request revisions.`,
+      options: [
+        { id: "approve", label: "Approve", style: "primary" },
+        { id: "reject", label: "Request Revisions", style: "danger" },
+      ],
+      reviewUrl,
+
+    };
+
+    // Defer the decision post until after the Operator relay completes,
+    // so the Operator's "PRD complete" message appears first.
+    this._deferredDecisions[feature.id] = { decision, featureId: feature.id };
+
+    // Notify the Operator — when the relay finishes, _postDeferredDecision() fires.
+    this._notifyOperatorOfDecision(feature, decision, output);
+  }
+
+  /**
+   * Notify the Operator about a pipeline decision via relay.
+   * Gives the Operator awareness and context regardless of adapter mode.
+   */
+  _notifyOperatorOfDecision(feature, decision, agentOutput) {
+    const optionsList = decision.options
+      .map(o => `${o.label} (id: ${o.id})`)
+      .join(", ");
+
+    const summary = agentOutput
+      ? `Agent output summary: ${agentOutput.slice(0, 500)}`
+      : "";
+
+    const reviewLine = decision.reviewUrl
+      ? `Review URL: ${decision.reviewUrl} (user can annotate feedback in browser)`
+      : "";
+    const qaLine = decision.qaUrl
+      ? `QA Test URL: ${decision.qaUrl} (user can test the live app)`
+      : "";
+
+    const content = [
+      `Pipeline event: ${decision.title}`,
+      decision.context || "",
+      `Decision ID: ${decision.id}`,
+      `Options: ${optionsList}`,
+      reviewLine,
+      qaLine,
+      summary,
+    ].filter(Boolean).join("\n");
+
+    this._enqueueForOperatorRelay(feature, "Pipeline", "decision-needed", content);
+  }
+
+  /**
+   * Re-post a pending phase review decision on resume.
+   * Called when a feature is in awaiting_phase_review state but the decision
+   * prompt was lost (e.g. terminal session died).
+   */
+  async repostPendingPhaseReview(featureId) {
+    const feature = queries.getFeatureById(featureId);
+    if (!feature) return;
+    const meta = queries.getFeatureMetadata(featureId);
+    if (!meta.awaiting_phase_review || !meta.phase_review_role) return;
+
+    const role = meta.phase_review_role;
+    const label = PLANNING_ROLE_LABELS[role] || role;
+    const nextRole = PIPELINE_ORDER[PIPELINE_ORDER.indexOf(role) + 1];
+    const nextLabel = nextRole ? (PLANNING_ROLE_LABELS[nextRole] || nextRole) : "Plan Approval";
+    const decisionId = `phase-review-${feature.slug}-${role}`;
+
+    // Upload artifacts again so the user can review
+    const planDir = path.join(feature.signal_dir, "plans");
+    const ARTIFACT_MAP = {
+      pm: [{ name: "PRD", pattern: "prd" }],
+      designer: [
+        { name: "Design Decisions", pattern: "design-decisions" },
+        { name: "UI Mockup", file: "mockup.html" },
+      ],
+      architect: [
+        { name: "Implementation Plan (plan.yaml)", file: "plan.yaml" },
+        { name: "Architecture Context", pattern: "context" },
+      ],
+    };
+    const artifacts = ARTIFACT_MAP[role] || [];
+
+    // Restore or start mockup session for designer phase
+    if (role === "designer" && this.reviewSessions) {
+      await this._ensureMockupSession(planDir, `${decisionId}-mockup`, feature.id);
+    }
+
+    // Restore or start review session for the primary artifact
+    let reviewUrl = null;
+    if (this.reviewSessions) {
+      reviewUrl = await this.reviewSessions.restoreSession(decisionId);
+      if (!reviewUrl) {
+        // No saved session — start a fresh one
+        const primaryArtifact = artifacts[0];
+        const primaryPath = primaryArtifact?.file
+          ? (fs.existsSync(path.join(planDir, primaryArtifact.file)) ? path.join(planDir, primaryArtifact.file) : null)
+          : findArtifact(primaryArtifact?.pattern, planDir);
+        if (primaryPath) {
+          reviewUrl = await this.reviewSessions.startDocReview(
+            decisionId, primaryPath, primaryArtifact.name, { featureId: feature.id }
+          );
+        }
+      }
+    }
+
+    // Only upload raw artifacts if no review session (fallback for non-review mode)
+    if (!reviewUrl) {
+      for (const artifact of artifacts) {
+        const artifactPath = artifact.file
+          ? (fs.existsSync(path.join(planDir, artifact.file)) ? path.join(planDir, artifact.file) : null)
+          : findArtifact(artifact.pattern, planDir);
+        if (artifactPath) {
+          await this.adapter.uploadArtifact(feature.id, artifactPath, artifact.name);
+        }
+      }
+    }
+
+    const decision = {
+      id: decisionId,
+      title: `${label} phase complete — review the ${artifacts[0]?.name || "output"} above`,
+      context: `Approve to proceed to ${nextLabel}, or reject to request revisions.`,
+      options: [
+        { id: "approve", label: "Approve", style: "primary" },
+        { id: "reject", label: "Request Revisions", style: "danger" },
+      ],
+      reviewUrl,
+
+    };
+
+    // Post decision directly — no deferred/Operator relay for reposts
+    await this.adapter.postDecision(feature.id, decision);
+  }
+
+  /**
+   * Re-present any pending decision on resume (restart/reconnect).
+   * Looks up the pending decision from DB and re-notifies the Operator.
+   */
+  async repostPendingDecision(featureId) {
+    const feature = queries.getFeatureById(featureId);
+    if (!feature) return;
+
+    // Check for awaiting_phase_review first — has its own richer repost logic
+    const meta = queries.getFeatureMetadata(featureId);
+    if (meta.awaiting_phase_review) {
+      return this.repostPendingPhaseReview(featureId);
+    }
+
+    // Check for plan-approval phase
+    if (feature.phase === "plan-approval") {
+      // Restore or start plan review session
+      let reviewUrl = null;
+      if (this.reviewSessions) {
+        reviewUrl = await this.reviewSessions.restoreSession("plan-approval");
+        if (!reviewUrl) {
+          // No prior session — compile and start fresh
+          const planDir = path.join(feature.signal_dir, "plans");
+          const compiledPath = compilePlanReviewHtml(planDir);
+          if (compiledPath) {
+            reviewUrl = await this.reviewSessions.startDocReview(
+              "plan-approval", compiledPath, "Plan Review", { featureId }
+            );
+          }
+        }
+      }
+
+      const decision = {
+        id: "plan-approval",
+        title: "Plan ready for approval",
+        context: "All planning phases complete. Review the artifacts.",
+        options: [
+          { id: "approve", label: "Approve Plan", style: "primary" },
+          { id: "reject", label: "Reject Plan", style: "danger" },
+        ],
+        reviewUrl,
+  
+      };
+      await this.adapter.postDecision(feature.id, decision);
+      this._notifyOperatorOfDecision(feature, decision);
+      return;
+    }
+
+    // Generic: re-notify for any pending decision in DB
+    const pendingDecision = queries.getPendingDecision(featureId);
+    if (pendingDecision) {
+      const options = JSON.parse(pendingDecision.options || "[]");
+      const decision = {
+        id: pendingDecision.decision_id,
+        title: pendingDecision.title || pendingDecision.decision_id,
+        context: pendingDecision.context_text || "",
+        options,
+      };
+      this._notifyOperatorOfDecision(feature, decision);
+    }
+  }
+
+  /**
+   * Handle phase review approval — advance to next planning role.
+   */
+  async handlePhaseReviewApproval(featureId) {
+    const feature = queries.getFeatureById(featureId);
+    if (!feature) return;
+
+    const meta = queries.getFeatureMetadata(featureId);
+    const role = meta.phase_review_role;
+    if (!role) return;
+
+    const label = PLANNING_ROLE_LABELS[role] || role;
+
+    // Clear review state
+    meta.awaiting_phase_review = false;
+    meta.phase_review_role = null;
+    meta.phase_review_ts = null;
+    queries.updateFeatureMetadata(featureId, meta);
+
+    const currentIndex = PIPELINE_ORDER.indexOf(role);
+    if (currentIndex >= 0 && currentIndex < PIPELINE_ORDER.length - 1) {
+      const nextRole = PIPELINE_ORDER[currentIndex + 1];
+      const nextLabel = PLANNING_ROLE_LABELS[nextRole] || nextRole;
+
+      await this.adapter.postPipelineMessage(feature.id,
+        `${label} approved. Starting ${nextLabel}...`);
+
+      db.transaction(() => {
+        queries.updateFeaturePlanningRole(feature.id, nextRole);
+      });
+
+      this.dispatchPlanningRole(feature.id, nextRole);
+    }
+
+    queries.insertEvent(featureId, "phase-transition", "bridge", `${role} phase approved`);
+  }
+
+  /**
+   * Handle phase review rejection — re-dispatch same role with feedback.
+   */
+  async handlePhaseReviewRejection(featureId, reason) {
+    const feature = queries.getFeatureById(featureId);
+    if (!feature) return;
+
+    const meta = queries.getFeatureMetadata(featureId);
+    const role = meta.phase_review_role;
+    if (!role) return;
+
+    const label = PLANNING_ROLE_LABELS[role] || role;
+
+    // Clear review state
+    meta.awaiting_phase_review = false;
+    meta.phase_review_role = null;
+    meta.phase_review_ts = null;
+    queries.updateFeatureMetadata(featureId, meta);
+
+    await this.adapter.postPipelineMessage(feature.id,
+      `Revision requested for ${label}: "${reason || "Please revise."}". Re-dispatching...`);
+
+    const roleDir = path.join(feature.signal_dir, "planning", role);
+    ensureDir(roleDir);
+
+    // Clean up stale .done/.output so file watcher doesn't immediately re-trigger
+    for (const sig of [SIGNAL.DONE, SIGNAL.OUTPUT]) {
+      try { fs.unlinkSync(path.join(roleDir, sig)); } catch { /* ok */ }
+    }
+
+    // Check if the agent has a prior session to continue
+    const agentKey = `${role}-${feature.slug}`;
+    const agent = queries.getAgentByKey(agentKey);
+
+    if (agent?.started_at != null) {
+      // Agent has prior session — use --continue with just the revision feedback
+      // No need to rebuild full prompt; the agent has full prior context
+      const revisionPrompt = `REVISION REQUESTED by the user:\n\n${reason || "Please revise your output."}\n\nIMPORTANT PROTOCOL:\n- If the feedback is unclear or you need clarification, write your question to .agent-response and then poll for .user-message (while [ ! -f .user-message ]; do sleep 5; done). Do NOT write .done until you have received the user's answer and completed your revision.\n- Do NOT write .done if you are asking a question. You must wait for the response first.\n- Only write .done after the revision is fully complete.`;
+
+      this.supervisor.kill(agentKey);
+      queries.updateAgentStatus(agent.id, "idle");
+      queries.resetAgentRetry(agent.id);
+      this.supervisor.spawn(agent.id, revisionPrompt, { continue: true });
+    } else {
+      // No prior session — fall back to full re-dispatch with revision context
+      writeSignal(path.join(roleDir, SIGNAL.USER_MESSAGE),
+        `REVISION REQUESTED: ${reason || "Please revise your output."}\n\nIMPORTANT PROTOCOL:\n- If the feedback is unclear or you need clarification, write your question to .agent-response and then poll for .user-message (while [ ! -f .user-message ]; do sleep 5; done). Do NOT write .done until you have received the user's answer and completed your revision.\n- Do NOT write .done if you are asking a question. You must wait for the response first.\n- Only write .done after the revision is fully complete.`);
+      this.dispatchPlanningRole(featureId, role, { continue: false });
+    }
+
+    queries.insertEvent(featureId, "phase-transition", "bridge", `${role} phase rejected: ${reason}`);
+  }
+
+  /**
+   * Handle plan approval — create branches and launch implementation directly.
+   */
+  async handlePlanApproval(featureId) {
+    const feature = queries.getFeatureById(featureId);
+    if (!feature) return;
+
+    if (this.deferImplLaunch) {
+      // CLI mode: don't auto-launch impl. CLI will prompt "continue to impl?" and
+      // call startImplementation() separately.
+      queries.insertEvent(featureId, "phase-transition", "bridge", "Plan approved (impl deferred to CLI prompt)");
+      return;
+    }
+
+    // Normal mode (Slack): create branches + launch implementation immediately
+    await this.startImplementation(featureId);
+  }
+
+  /**
+   * Start implementation for a feature: create branches, run launch script, spawn agents.
+   * Extracted from handlePlanApproval() so the CLI can call it independently after
+   * prompting "Continue to implementation?"
+   */
+  async startImplementation(featureId) {
+    const feature = queries.getFeatureById(featureId);
+    if (!feature) return;
+
+    const planDir = path.join(feature.signal_dir, "plans");
+    const detectedRepos = detectReposFromPlan(planDir, feature.slug);
+    const meta = queries.getFeatureMetadata(featureId);
+    const newRepos = meta.new_repos || [];
+
+    try {
+      // Create feature branches
+      if (detectedRepos.length > 0 || newRepos.length > 0) {
+        const completeScript = path.join(SCRIPTS_DIR, "planning-complete.sh");
+        if (fs.existsSync(completeScript)) {
+          const newFlags = newRepos.map(nr => `--new "${nr.localPath}" "${nr.githubName}"`);
+          const newRepoPaths = new Set(newRepos.map(r => r.localPath));
+          const existingArgs = detectedRepos.filter(r => !newRepoPaths.has(r)).map(r => `"${r}"`);
+          const args = [`"${feature.slug}"`, ...newFlags, ...existingArgs].join(" ");
+
+          execSync(`bash "${completeScript}" ${args}`, {
+            cwd: IRIAI_TEAM_DIR, stdio: "pipe", timeout: 120000,
+            env: { ...process.env, PLAN_DIR: planDir, CONFIRM: "y" },
+          });
+        }
+      }
+
+      // Run launch script if it exists
+      const launchScript = path.join(SCRIPTS_DIR, "launch-feature.sh");
+      if (fs.existsSync(launchScript)) {
+        execSync(`bash "${launchScript}" "${feature.slug}"`, {
+          cwd: IRIAI_TEAM_DIR, stdio: "pipe", timeout: 300000,
+          env: {
+            ...process.env,
+            IMPL_SIGNAL_BASE: IMPL_BASE,
+            SLACK_MODE: "true",
+            FEATURE_SLUG: feature.slug,
+            IMPL_CHANNEL: feature.feature_channel || "",
+            PLAN_DIR: planDir,
+            ROLES_DIR: V3_ROLES_DIR,
+          },
+        });
+      }
+
+      // Launch implementation agents
+      this.launchImplAgents(featureId);
+
+      db.transaction(() => {
+        queries.updateFeaturePhase(featureId, "impl");
+      });
+
+      queries.insertEvent(featureId, "phase-transition", "bridge", "Implementation launched");
+    } catch (err) {
+      console.error("[orchestrator] Implementation launch error:", err.message);
+      const stderr = err.stderr ? err.stderr.toString().slice(-500) : err.message;
+      await this.adapter.postPipelineMessage(feature.id,
+        `Error launching implementation:\n\`\`\`${stderr}\`\`\``);
+    }
+  }
+
+  /**
+   * Handle plan rejection — re-dispatch architect.
+   */
+  async handlePlanRejection(featureId, reason) {
+    const feature = queries.getFeatureById(featureId);
+    if (!feature) return;
+
+    await this.adapter.postPipelineMessage(feature.id,
+      `Plan rejected. Re-dispatching Architect with feedback...`);
+
+    db.transaction(() => {
+      queries.updateFeaturePhase(featureId, "planning");
+      queries.updateFeaturePlanningRole(featureId, "architect");
+    });
+
+    const archDir = path.join(feature.signal_dir, "planning", "architect");
+    ensureDir(archDir);
+    writeSignal(path.join(archDir, SIGNAL.USER_MESSAGE),
+      `REVISION REQUESTED: ${reason || "Plan rejected. Please revise."}`);
+
+    this.dispatchPlanningRole(featureId, "architect");
+    queries.insertEvent(featureId, "phase-transition", "bridge", `Plan rejected: ${reason}`);
+  }
+
+  /**
+   * Handle repo confirmation ("go") — create branches and launch implementation.
+   */
+  async handleRepoConfirmation(featureId) {
+    const feature = queries.getFeatureById(featureId);
+    if (!feature) return;
+
+    const meta = queries.getFeatureMetadata(featureId);
+    const repos = meta.pending_repos || [];
+    const newRepos = meta.new_repos || [];
+    meta.awaiting_repo_confirm = false;
+    meta.pending_repos = null;
+    queries.updateFeatureMetadata(featureId, meta);
+
+    const planDir = path.join(feature.signal_dir, "plans");
+    try {
+      if (repos.length > 0 || newRepos.length > 0) {
+        const totalCount = repos.length + newRepos.filter(nr => !repos.includes(nr.localPath)).length;
+        await this.adapter.postThreadMessage(feature.id,
+          `*[Pipeline]* Creating \`feature/${feature.slug}\` branches in ${totalCount} repo(s)...`);
+
+        const completeScript = path.join(SCRIPTS_DIR, "planning-complete.sh");
+        if (fs.existsSync(completeScript)) {
+          // Build --new flags for new repos
+          const newFlags = newRepos.map(nr => `--new "${nr.localPath}" "${nr.githubName}"`);
+          // Existing repos (exclude new repo paths that will be handled by --new)
+          const newRepoPaths = new Set(newRepos.map(r => r.localPath));
+          const existingArgs = repos.filter(r => !newRepoPaths.has(r)).map(r => `"${r}"`);
+
+          const args = [
+            `"${feature.slug}"`,
+            ...newFlags,
+            ...existingArgs,
+          ].join(" ");
+
+          execSync(
+            `bash "${completeScript}" ${args}`,
+            {
+              cwd: IRIAI_TEAM_DIR, stdio: "pipe", timeout: 120000,
+              env: { ...process.env, PLAN_DIR: planDir, CONFIRM: "y" },
+            }
+          );
+        }
+        await this.adapter.postThreadMessage(feature.id,
+          `*[Pipeline]* Feature branches created. Launching implementation...`);
+      } else {
+        await this.adapter.postThreadMessage(feature.id,
+          `*[Pipeline]* No repos configured — skipping branch creation. Launching implementation...`);
+      }
+
+      const launchScript = path.join(SCRIPTS_DIR, "launch-feature.sh");
+      if (fs.existsSync(launchScript)) {
+        try {
+          execSync(`bash "${launchScript}" "${feature.slug}"`, {
+            cwd: IRIAI_TEAM_DIR, stdio: "pipe", timeout: 300000,
+            env: {
+              ...process.env,
+              IMPL_SIGNAL_BASE: IMPL_BASE,
+              SLACK_MODE: "true",
+              FEATURE_SLUG: feature.slug,
+              IMPL_CHANNEL: feature.feature_channel || "",
+              PLAN_DIR: planDir,
+              ROLES_DIR: V3_ROLES_DIR,
+            },
+          });
+        } catch (launchErr) {
+          console.error("[orchestrator] launch-feature.sh failed:", launchErr.message);
+          const stderr = launchErr.stderr ? launchErr.stderr.toString().slice(-500) : launchErr.message;
+          await this.adapter.postThreadMessage(feature.id,
+            `*[Pipeline]* Error setting up implementation:\n\`\`\`${stderr}\`\`\``);
+          meta.awaiting_repo_confirm = true;
+          queries.updateFeatureMetadata(featureId, meta);
+          return;
+        }
+      }
+
+      // Launch implementation agents
+      this.launchImplAgents(featureId);
+
+      db.transaction(() => {
+        queries.updateFeaturePhase(featureId, "impl");
+      });
+
+      queries.insertEvent(featureId, "phase-transition", "bridge", "Implementation launched");
+    } catch (err) {
+      const stderr = err.stderr ? err.stderr.toString().slice(-500) : err.message;
+      await this.adapter.postThreadMessage(feature.id,
+        `*[Pipeline]* Error creating branches:\n\`\`\`${stderr}\`\`\`\nRetry by replying "go" again.`);
+      meta.awaiting_repo_confirm = true;
+      queries.updateFeatureMetadata(featureId, meta);
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // IMPLEMENTATION PIPELINE
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Discover the signal tree for a feature slug.
+   */
+  discoverSignalTree(slug) {
+    const featureDir = path.join(IMPL_BASE, "features", slug);
+    const tree = {
+      featureDir,
+      featureLead: null,
+      operator: null,
+      featureReview: {},
+      teams: {},
+      planning: {},
+      plansDir: null,
+    };
+
+    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");
+    if (fs.existsSync(reviewDir)) {
+      try {
+        for (const entry of fs.readdirSync(reviewDir, { withFileTypes: true })) {
+          if (entry.isDirectory()) {
+            tree.featureReview[entry.name] = path.join(reviewDir, entry.name);
+          }
+        }
+      } catch { /* ok */ }
+    }
+
+    const teamsDir = path.join(featureDir, "teams");
+    if (fs.existsSync(teamsDir)) {
+      try {
+        for (const entry of fs.readdirSync(teamsDir, { withFileTypes: true })) {
+          if (!entry.isDirectory() || !entry.name.startsWith("team-")) continue;
+          const teamNum = entry.name.replace("team-", "");
+          const teamDir = path.join(teamsDir, entry.name);
+          const orchDir = path.join(teamDir, "orchestrator");
+          const roles = {};
+          const rolesDir = path.join(teamDir, "roles");
+          if (fs.existsSync(rolesDir)) {
+            for (const roleEntry of fs.readdirSync(rolesDir, { withFileTypes: true })) {
+              if (roleEntry.isDirectory()) {
+                roles[roleEntry.name] = path.join(rolesDir, roleEntry.name);
+              }
+            }
+          }
+          tree.teams[teamNum] = {
+            dir: teamDir,
+            orchestrator: fs.existsSync(orchDir) ? orchDir : null,
+            roles,
+          };
+        }
+      } catch { /* ok */ }
+    }
+
+    // Planning dirs
+    const planningDir = path.join(featureDir, "planning");
+    if (fs.existsSync(planningDir)) {
+      for (const role of PLANNING_ROLES) {
+        const roleDir = path.join(planningDir, role);
+        if (fs.existsSync(roleDir)) tree.planning[role] = roleDir;
+      }
+    }
+
+    const plansDir = path.join(featureDir, "plans");
+    if (fs.existsSync(plansDir)) tree.plansDir = plansDir;
+
+    this._signalTrees[slug] = tree;
+    return tree;
+  }
+
+  /**
+   * Create per-team worktrees from the feature-level repos.
+   * For each repo at .features/<slug>/repos/<basename>/ (on feature/<slug> branch),
+   * creates .features/<slug>/teams/<teamNum>/repos/<basename>/ on feature/<slug>/team-<teamNum> branch.
+   */
+  _createTeamWorktrees(feature, numTeams) {
+    const featuresBase = path.join(process.env.HOME, "src/iriai/.features", feature.slug);
+    const reposDir = path.join(featuresBase, "repos");
+    if (!fs.existsSync(reposDir)) return;
+
+    const repos = fs.readdirSync(reposDir).filter(name => {
+      const repoPath = path.join(reposDir, name);
+      // Worktrees have a .git file (not directory), regular repos have .git directory
+      return fs.statSync(repoPath).isDirectory() && fs.existsSync(path.join(repoPath, ".git"));
+    });
+
+    if (repos.length === 0) return;
+
+    const featureBranch = `feature/${feature.slug}`;
+
+    for (let teamNum = 1; teamNum <= numTeams; teamNum++) {
+      const teamReposDir = path.join(featuresBase, "teams", String(teamNum), "repos");
+      ensureDir(teamReposDir);
+
+      for (const repoName of repos) {
+        const featureRepoPath = path.join(reposDir, repoName);
+        const teamWorktreeDest = path.join(teamReposDir, repoName);
+        const teamBranch = `${featureBranch}/team-${teamNum}`;
+
+        // Skip if team worktree already exists
+        if (fs.existsSync(teamWorktreeDest)) continue;
+
+        try {
+          // Create team branch from feature branch if it doesn't exist
+          try {
+            execSync(`git -C "${featureRepoPath}" branch "${teamBranch}" "${featureBranch}" 2>/dev/null || true`, { stdio: "pipe" });
+          } catch { /* branch may already exist */ }
+
+          // Create worktree for this team
+          execSync(
+            `git -C "${featureRepoPath}" worktree add "${teamWorktreeDest}" "${teamBranch}"`,
+            { stdio: "pipe", timeout: 30000 }
+          );
+          console.log(`[orchestrator] Created team worktree: ${repoName} → team-${teamNum} (${teamBranch})`);
+        } catch (err) {
+          // Try with -b flag as fallback
+          try {
+            execSync(
+              `git -C "${featureRepoPath}" worktree add "${teamWorktreeDest}" -b "${teamBranch}" 2>/dev/null || git -C "${featureRepoPath}" worktree add "${teamWorktreeDest}" "${teamBranch}"`,
+              { stdio: "pipe", timeout: 30000 }
+            );
+            console.log(`[orchestrator] Created team worktree (fallback): ${repoName} → team-${teamNum}`);
+          } catch (err2) {
+            console.error(`[orchestrator] Failed to create team worktree for ${repoName} team-${teamNum}:`, err2.message);
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * Launch all implementation agents for a feature.
+   */
+  launchImplAgents(featureId) {
+    const feature = queries.getFeatureById(featureId);
+    if (!feature) return;
+
+    const tree = this.discoverSignalTree(feature.slug);
+    const numTeams = Object.keys(tree.teams).length || feature.num_teams;
+    const worktreeDir = path.join(process.env.HOME, "src/iriai/.features", feature.slug);
+    const featureCwd = fs.existsSync(worktreeDir) ? worktreeDir : IRIAI_TEAM_DIR;
+
+    // Create per-team worktrees so each team works on its own branch
+    this._createTeamWorktrees(feature, numTeams);
+
+    // Feature Lead
+    if (tree.featureLead) {
+      let flAgent = queries.getAgentByKey(`fl-${feature.slug}`);
+      if (!flAgent) {
+        flAgent = queries.createAgent({
+          featureId,
+          agentType: "feature-lead",
+          agentKey: `fl-${feature.slug}`,
+          roleName: "feature-lead",
+          signalDir: tree.featureLead,
+          cwd: featureCwd,
+          maxRetries: MAX_FL_RETRIES,
+        });
+      } else {
+        this._syncAgentRetries(flAgent, MAX_FL_RETRIES);
+      }
+
+      // Use "refresh" mode if FEATURE-STATUS.md exists (recovery/restart scenario)
+      const featureStatusPath = path.join(tree.featureDir, "FEATURE-STATUS.md");
+      const flMode = fs.existsSync(featureStatusPath) ? "refresh" : "init";
+      // On recovery: if FL has prior session and no .handover, use --continue
+      const flHasHandover = fs.existsSync(path.join(tree.featureLead, SIGNAL.HANDOVER));
+      const flHasSession = flAgent.started_at != null;
+      const flContinue = flHasSession && !flHasHandover && flMode === "refresh";
+      this._spawnFeatureLead(flAgent.id, feature, tree, flMode, { continue: flContinue });
+    }
+
+    // Operator
+    if (tree.operator) {
+      let opAgent = queries.getAgentByKey(`op-${feature.slug}`);
+      if (!opAgent) {
+        opAgent = queries.createAgent({
+          featureId,
+          agentType: "operator",
+          agentKey: `op-${feature.slug}`,
+          roleName: "operator",
+          signalDir: tree.operator,
+          cwd: featureCwd,
+          maxRetries: MAX_OPERATOR_RETRIES,
+        });
+      } else {
+        this._syncAgentRetries(opAgent, MAX_OPERATOR_RETRIES);
+      }
+      // Operator is reactive — spawned by routeUserMessage
+      queries.updateAgentStatus(opAgent.id, "idle");
+    }
+
+    // Team Orchestrators
+    for (const [teamNum, team] of Object.entries(tree.teams)) {
+      // Per-team CWD: use team-specific worktree if it exists, else fall back to feature-level
+      const teamWorktreeDir = path.join(process.env.HOME, "src/iriai/.features", feature.slug, "teams", teamNum, "repos");
+      const teamCwd = fs.existsSync(teamWorktreeDir) ? path.join(process.env.HOME, "src/iriai/.features", feature.slug, "teams", teamNum) : featureCwd;
+
+      if (team.orchestrator) {
+        const orchKey = `orch-${feature.slug}-${teamNum}`;
+        let orchAgent = queries.getAgentByKey(orchKey);
+        if (!orchAgent) {
+          orchAgent = queries.createAgent({
+            featureId,
+            agentType: "team-orchestrator",
+            agentKey: orchKey,
+            teamNum,
+            signalDir: team.orchestrator,
+            cwd: teamCwd,
+            maxRetries: MAX_ORCH_RETRIES,
+          });
+        } else {
+          this._syncAgentRetries(orchAgent, MAX_ORCH_RETRIES);
+        }
+        // Orchestrator waits for .task — no auto-start
+      }
+
+      // Role Agents
+      for (const [role, roleDir] of Object.entries(team.roles)) {
+        const roleKey = `role-${feature.slug}-${teamNum}-${role}`;
+        let roleAgent = queries.getAgentByKey(roleKey);
+        if (!roleAgent) {
+          roleAgent = queries.createAgent({
+            featureId,
+            agentType: "role-agent",
+            agentKey: roleKey,
+            roleName: role,
+            teamNum,
+            signalDir: roleDir,
+            cwd: teamCwd,
+            maxRetries: MAX_ROLE_RETRIES,
+          });
+        } else {
+          this._syncAgentRetries(roleAgent, MAX_ROLE_RETRIES);
+        }
+        // Role waits for .task — no auto-start
+      }
+    }
+
+    // Feature Review Roles
+    for (const [role, reviewDir] of Object.entries(tree.featureReview)) {
+      const reviewKey = `review-${feature.slug}-${role}`;
+      let reviewAgent = queries.getAgentByKey(reviewKey);
+      if (!reviewAgent) {
+        reviewAgent = queries.createAgent({
+          featureId,
+          agentType: "review-agent",
+          agentKey: reviewKey,
+          roleName: role,
+          signalDir: reviewDir,
+          cwd: featureCwd,
+          maxRetries: MAX_ROLE_RETRIES,
+        });
+      } else {
+        this._syncAgentRetries(reviewAgent, MAX_ROLE_RETRIES);
+      }
+    }
+
+    // Watch signals
+    this.fileIO.watchFeatureSignals(feature.slug, tree);
+
+    console.log(`[orchestrator] Launched impl agents for ${feature.slug}: FL + operator + ${numTeams} teams`);
+  }
+
+  /**
+   * Sync max_retries from current constants to existing DB agent records.
+   */
+  _syncAgentRetries(agent, expectedMaxRetries) {
+    if (agent.max_retries !== expectedMaxRetries) {
+      queries.updateAgentMaxRetries(agent.id, expectedMaxRetries);
+    }
+    // Reset crashed agents so they can be retried
+    if (agent.status === "crashed") {
+      queries.updateAgentStatus(agent.id, "idle");
+      queries.resetAgentRetry(agent.id);
+    }
+  }
+
+  /**
+   * Spawn (or re-spawn) the Feature Lead agent.
+   */
+  _spawnFeatureLead(agentId, feature, tree, mode, opts = {}) {
+    const numTeams = Object.keys(tree.teams).length || feature.num_teams;
+    const teamSignalBase = path.join(tree.featureDir, "teams");
+    const featureReviewDir = path.join(tree.featureDir, "feature-review");
+
+    // Resolve plan read instruction
+    const planReadInstruction = this._resolvePlanInstruction(tree.featureLead, tree.featureDir);
+
+    let prompt;
+    switch (mode) {
+      case "init":
+        prompt = buildFeatureLeadInitPrompt({
+          featureName: feature.slug,
+          numTeams,
+          teamType: "dynamic",
+          teamSignalBase,
+          planReadInstruction,
+          featureLeadDir: tree.featureLead,
+          featureReviewDir,
+          dashboardLog: path.join(tree.featureDir, ".dashboard-log"),
+          featureDir: tree.featureDir,
+          teamWorktreeBase: path.join(process.env.HOME, "src/iriai/.features", feature.slug, "teams"),
+        });
+        break;
+
+      case "refresh":
+        prompt = buildFeatureLeadRefreshPrompt({
+          featureName: feature.slug,
+          numTeams,
+          teamSignalBase,
+          planReadInstruction,
+          featureLeadDir: tree.featureLead,
+          featureReviewDir,
+          dashboardLog: path.join(tree.featureDir, ".dashboard-log"),
+          gateEvidenceTs: feature.gate_evidence_ts,
+          featureDir: tree.featureDir,
+          teamWorktreeBase: path.join(process.env.HOME, "src/iriai/.features", feature.slug, "teams"),
+        });
+        break;
+
+      case "trigger":
+        prompt = buildFeatureLeadTriggerPrompt({
+          featureName: feature.slug,
+          numTeams,
+          trigger: opts.trigger,
+          teamSignalBase,
+          featureLeadDir: tree.featureLead,
+          featureReviewDir,
+          dashboardLog: path.join(tree.featureDir, ".dashboard-log"),
+          questionTeams: opts.questionTeams,
+          crashedTeams: opts.crashedTeams,
+          recoveryContext: opts.recoveryContext,
+          featureDir: tree.featureDir,
+          teamWorktreeBase: path.join(process.env.HOME, "src/iriai/.features", feature.slug, "teams"),
+        });
+        break;
+    }
+
+    // Prepend handover content if available
+    if (opts.handoverContent) {
+      prompt = `HANDOVER CONTEXT FROM PREVIOUS SESSION:\n${opts.handoverContent}\n\n---\n\n${prompt}`;
+    }
+
+    // Use --continue if FL has prior session and this isn't a fresh start (handover/refresh)
+    // Handover = context exhausted, must start fresh. Trigger = can continue prior conversation.
+    const useContinue = opts.continue !== undefined
+      ? opts.continue
+      : (!opts.handoverContent && mode === "trigger");
+    this.supervisor.spawn(agentId, prompt, { continue: useContinue });
+    queries.insertEvent(feature.id, "agent-started", "bridge", `Feature Lead spawned (${mode})`);
+  }
+
+  _resolvePlanInstruction(featureLeadDir, featureDir) {
+    // Check for .feature-proposal with custom plan paths
+    const proposalPath = path.join(featureLeadDir, ".feature-proposal");
+    if (fs.existsSync(proposalPath)) {
+      const content = fs.readFileSync(proposalPath, "utf-8");
+      const planMatch = content.match(/plan_path:\s*(.+)/);
+      if (planMatch) return `Read the implementation plan at: ${planMatch[1].trim()}`;
+    }
+    // Check per-feature plans dir first
+    const perFeaturePlansDir = path.join(featureDir, "plans");
+    if (fs.existsSync(perFeaturePlansDir)) {
+      return `Read the implementation plan in ${perFeaturePlansDir}/`;
+    }
+    return `Read the implementation plan in ~/src/iriai/iriai-team/implementation-plans/current/`;
+  }
+
+  // ─── Gate Handling ──────────────────────────────────────────────────────
+
+  async handleGateApproval(featureId) {
+    const feature = queries.getFeatureById(featureId);
+    if (!feature) return;
+    const tree = this._signalTrees[feature.slug];
+    if (!tree?.featureLead) return;
+
+    writeSignal(path.join(tree.featureLead, SIGNAL.USER_MESSAGE),
+      "GATE APPROVED. Advance all teams to the next phase.");
+
+    queries.updateFeatureGateEvidenceTs(featureId, null);
+    queries.updateFeatureGate(featureId, (feature.gate_number || 0) + 1);
+    queries.insertEvent(featureId, "gate-approved", "bridge", `Gate ${(feature.gate_number || 0) + 1} approved by user`);
+  }
+
+  async handleGateRejection(featureId, reason) {
+    const feature = queries.getFeatureById(featureId);
+    if (!feature) return;
+    const tree = this._signalTrees[feature.slug];
+    if (!tree?.featureLead) return;
+
+    writeSignal(path.join(tree.featureLead, SIGNAL.USER_MESSAGE),
+      `GATE REJECTED: ${reason || "Please revise and resubmit."}`);
+
+    queries.updateFeatureGateEvidenceTs(featureId, null);
+    queries.insertEvent(featureId, "gate-rejected", "bridge", `Gate rejected: ${reason}`);
+  }
+
+  // ─── Decision Click Routing (Block Kit Buttons) ──────────────────────
+
+  async handleDecisionClick(decisionId, optionId, userId, channel, messageTs, feedback = "") {
+    // Collect annotations from review session and enrich rejection feedback
+    let enrichedFeedback = feedback;
+    if (this.reviewSessions && optionId !== "approve") {
+      const annotations = await this.reviewSessions.collectFeedback(decisionId);
+      if (annotations && annotations.length > 0) {
+        enrichedFeedback = formatAnnotationsAsFeedback(annotations, feedback);
+      }
+    }
+
+    // Phase review: "phase-review-<slug>-<role>" (or legacy "phase-review-<role>")
+    if (decisionId.startsWith("phase-review-")) {
+      const suffix = decisionId.replace("phase-review-", "");
+      const features = queries.getActiveFeatures();
+
+      // New format: "phase-review-<slug>-<role>" — find feature by slug embedded in the ID
+      let feature = features.find(f => {
+        const m = queries.getFeatureMetadata(f.id);
+        if (!m.awaiting_phase_review) return false;
+        return suffix === `${f.slug}-${m.phase_review_role}`;
+      });
+
+      // Legacy fallback: "phase-review-<role>" — disambiguate by channel
+      if (!feature) {
+        const role = suffix;
+        feature = features.find(f => {
+          const m = queries.getFeatureMetadata(f.id);
+          if (!m.awaiting_phase_review || m.phase_review_role !== role) return false;
+          const fChannel = f.feature_channel || this.adapter.planningChannel;
+          return fChannel === channel;
+        });
+      }
+      if (!feature) return;
+
+      if (optionId === "approve") {
+        await this.handlePhaseReviewApproval(feature.id);
+      } else {
+        await this.handlePhaseReviewRejection(feature.id, enrichedFeedback || "Rejected via button");
+      }
+      await this._resolveDecisionMessage(feature.id, messageTs, decisionId, optionId, userId, feedback);
+      if (this.reviewSessions) {
+        await this.reviewSessions.stop(decisionId);
+        // Also stop mockup session if this was a designer review
+        await this.reviewSessions.stop(`${decisionId}-mockup`);
+      }
+      return;
+    }
+
+    // Plan approval: "plan-approval"
+    if (decisionId === "plan-approval") {
+      const features = queries.getActiveFeatures();
+      // Use channel to disambiguate when multiple features are in plan-approval
+      const feature = features.find(f => {
+        if (f.phase !== "plan-approval") return false;
+        const fChannel = f.feature_channel || this.adapter.planningChannel;
+        return fChannel === channel;
+      });
+      if (!feature) return;
+
+      if (optionId === "approve") {
+        await this.handlePlanApproval(feature.id);
+      } else {
+        await this.handlePlanRejection(feature.id, enrichedFeedback || "Rejected via button");
+      }
+      await this._resolveDecisionMessage(feature.id, messageTs, decisionId, optionId, userId, feedback);
+      if (this.reviewSessions) await this.reviewSessions.stop(decisionId);
+      return;
+    }
+
+    // Gate approval: "gate-*"
+    if (decisionId.startsWith("gate-")) {
+      const features = queries.getActiveFeatures();
+      const feature = features.find(f => f.feature_channel === channel && f.gate_evidence_ts);
+      if (!feature) return;
+
+      if (optionId === "approve") {
+        await this.handleGateApproval(feature.id);
+      } else {
+        await this.handleGateRejection(feature.id, enrichedFeedback || "Rejected via button");
+      }
+      await this._resolveDecisionMessage(feature.id, messageTs, decisionId, optionId, userId, feedback);
+      if (this.reviewSessions) await this.reviewSessions.stop(decisionId);
+      return;
+    }
+
+    // Custom [DECISION] — resolve in DB, notify agent
+    // Use slack_channel stored on the decision to match the correct feature
+    const decision = queries.getDecisionByChannel(channel, decisionId);
+    if (decision) {
+      queries.resolveDecision(decision.feature_id, decisionId, { selectedOption: optionId, resolvedBy: userId });
+      await this._resolveDecisionMessage(decision.feature_id, messageTs, decisionId, optionId, userId, feedback);
+      // Write decision result to operator for relay to active agent
+      const feature = queries.getFeatureById(decision.feature_id);
+      if (feature) {
+        const tree = this._signalTrees[feature.slug];
+        const targetDir = tree?.operator || tree?.featureLead;
+        if (targetDir) {
+          const options = JSON.parse(decision.options || "[]");
+          const option = options.find(o => o.id === optionId);
+          const feedbackSuffix = feedback ? `\nFeedback: ${feedback}` : "";
+          writeSignal(path.join(targetDir, SIGNAL.USER_MESSAGE),
+            `Decision "${decision.title}": User selected "${option?.label || optionId}"${feedbackSuffix}`);
+        }
+      }
+      return;
+    }
+  }
+
+  async _resolveDecisionMessage(featureId, messageTs, decisionId, selectedOptionId, userId, feedback = "") {
+    if (!featureId) return;
+
+    // Resolve the human-readable label for the selected option.
+    // First check DB (custom [DECISION] blocks are stored there), then fall back to defaults.
+    let selectedLabel = selectedOptionId;
+    const dbDecision = queries.getDecision(featureId, decisionId);
+    if (dbDecision) {
+      const options = JSON.parse(dbDecision.options || "[]");
+      const match = options.find(o => o.id === selectedOptionId);
+      if (match) selectedLabel = match.label;
+    } else {
+      // Built-in decisions (phase-review, plan-approval, gate) aren't in the DB
+      const FALLBACK_LABELS = { approve: "Approve", reject: "Reject" };
+      if (FALLBACK_LABELS[selectedOptionId]) {
+        selectedLabel = FALLBACK_LABELS[selectedOptionId];
+      }
+    }
+
+    try {
+      await this.adapter.resolveDecisionMessage(
+        featureId, messageTs, decisionId, selectedOptionId, selectedLabel, userId, feedback
+      );
+    } catch (err) {
+      console.error("[orchestrator] Failed to update decision message:", err.message);
+    }
+  }
+
+  // ─── User Message Routing ─────────────────────────────────────────────
+
+  async routeUserMessage(featureId, text) {
+    const feature = queries.getFeatureById(featureId);
+    if (!feature) return;
+
+    let enrichedText = text;
+
+    // If the user's message matches a pending decision option and there are
+    // doc review annotations, enrich the message so the Operator has them.
+    const trimmed = text.trim().toLowerCase();
+    const pendingDecision = this._findPendingDecisionForFeature(feature);
+    if (pendingDecision && this.reviewSessions) {
+      const matchedOption = pendingDecision.options.find(
+        o => o.id.toLowerCase() === trimmed
+      );
+      if (matchedOption) {
+        const annotations = await this.reviewSessions.collectFeedback(pendingDecision.id);
+        if (annotations && annotations.length > 0) {
+          const formatted = formatAnnotationsAsFeedback(annotations, null);
+          enrichedText = `${text}\n\n${formatted}`;
+        }
+      }
+    }
+
+    const tree = this._signalTrees[feature.slug];
+
+    // Route to operator, with FL fallback
+    const targetDir = tree?.operator || tree?.featureLead;
+    if (!targetDir) return;
+    ensureDir(targetDir);
+    writeSignal(path.join(targetDir, SIGNAL.USER_MESSAGE), enrichedText);
+  }
+
+  /**
+   * Find the active pending decision for a feature (phase review, plan approval, or gate).
+   * Returns { id, options } or null.
+   */
+  _findPendingDecisionForFeature(feature) {
+    const meta = queries.getFeatureMetadata(feature.id);
+
+    // Phase review
+    if (meta.awaiting_phase_review && meta.phase_review_role) {
+      return {
+        id: `phase-review-${feature.slug}-${meta.phase_review_role}`,
+        options: [
+          { id: "approve", label: "Approve" },
+          { id: "reject", label: "Request Revisions" },
+        ],
+      };
+    }
+
+    // Plan approval
+    if (feature.phase === "plan-approval") {
+      return {
+        id: "plan-approval",
+        options: [
+          { id: "approve", label: "Approve Plan" },
+          { id: "reject", label: "Reject Plan" },
+        ],
+      };
+    }
+
+    // Gate review
+    if (feature.gate_evidence_ts) {
+      return {
+        id: `gate-${(feature.gate_number || 0) + 1}-review`,
+        options: [
+          { id: "approve", label: "Approve" },
+          { id: "reject", label: "Reject" },
+        ],
+      };
+    }
+
+    // Custom decision from DB
+    const dbDecision = queries.getPendingDecision(feature.id);
+    if (dbDecision) {
+      return {
+        id: dbDecision.decision_id,
+        options: JSON.parse(dbDecision.options || "[]"),
+      };
+    }
+
+    return null;
+  }
+
+  /**
+   * Read the verification config from plan.yaml for a feature.
+   * Returns { type, command, url } or null if not present.
+   */
+  _readVerificationConfig(feature) {
+    try {
+      const planYamlPath = path.join(feature.signal_dir, "plans", "plan.yaml");
+      if (!fs.existsSync(planYamlPath)) return null;
+      const content = fs.readFileSync(planYamlPath, "utf-8");
+
+      // Extract the verification block (simple YAML subset — no nested objects)
+      const verMatch = content.match(/^verification:\s*\n((?:\s+\S.*\n?)*)/m);
+      if (!verMatch) return null;
+
+      const block = verMatch[1];
+      const type = block.match(/type:\s*(.+)/)?.[1]?.trim().replace(/["']/g, "") || null;
+      const command = block.match(/command:\s*["']?(.+?)["']?\s*$/m)?.[1]?.trim() || null;
+      const url = block.match(/url:\s*["']?(.+?)["']?\s*$/m)?.[1]?.trim() || null;
+
+      if (!type) return null;
+      return { type, command, url };
+    } catch {
+      return null;
+    }
+  }
+
+  // ─── Worktree Management ────────────────────────────────────────────
+
+  /**
+   * Handle .needs-repos signal from Operator — create git worktrees for requested repos.
+   * Each repo path (from DIRECTORY_MAP) gets a worktree at .features/<slug>/repos/<basename>/
+   */
+  async _handleNeedsRepos(feature, content) {
+    const lines = content.split("\n").map(l => l.trim()).filter(Boolean);
+    if (lines.length === 0) return;
+
+    const reposBase = path.join(process.env.HOME, "src/iriai/.features", feature.slug, "repos");
+    ensureDir(reposBase);
+
+    const featureBranch = `feature/${feature.slug}`;
+    const projectRoot = path.join(process.env.HOME, "src/iriai");
+    const created = [];
+    const scaffolded = [];
+    const skipped = [];
+    const failed = [];
+
+    // Separate new repos (+prefix) from existing repos
+    const existingRepoPaths = [];
+    const newRepoSpecs = [];
+    for (const line of lines) {
+      if (line.startsWith("+")) {
+        // Format: +<localPath>:<githubName>[:<template>]
+        const parts = line.slice(1).split(":");
+        if (parts.length >= 2) {
+          newRepoSpecs.push({
+            localPath: parts[0],
+            githubName: parts[1],
+            template: parts[2] || null,
+          });
+        }
+      } else {
+        existingRepoPaths.push(line);
+      }
+    }
+
+    // Handle new repos: scaffold locally, then proceed to worktree like existing
+    const meta = queries.getFeatureMetadata(feature.id);
+    const existingNewRepos = meta.new_repos || [];
+    const existingPaths = new Set(existingNewRepos.map(r => r.localPath));
+
+    for (const spec of newRepoSpecs) {
+      const repoName = path.basename(spec.localPath);
+      const worktreeDest = path.join(reposBase, repoName);
+
+      // Dedup: skip if already scaffolded in a prior .needs-repos call
+      if (fs.existsSync(worktreeDest)) {
+        skipped.push(repoName);
+        continue;
+      }
+
+      // Scaffold the repo locally (creates dir, template, git init)
+      const ok = scaffoldNewRepo(spec.localPath, spec.githubName, spec.template);
+      if (!ok) {
+        failed.push(repoName);
+        continue;
+      }
+      scaffolded.push(repoName);
+
+      // Store metadata for later use in handleRepoConfirmation
+      if (!existingPaths.has(spec.localPath)) {
+        existingNewRepos.push(spec);
+        existingPaths.add(spec.localPath);
+      }
+
+      // Now treat as an existing repo for worktree creation
+      existingRepoPaths.push(spec.localPath);
+    }
+
+    // Persist new_repos metadata
+    if (newRepoSpecs.length > 0) {
+      meta.new_repos = existingNewRepos;
+      queries.updateFeatureMetadata(feature.id, meta);
+    }
+
+    // Handle existing repos (+ newly scaffolded ones): create worktrees
+    for (const repoPath of existingRepoPaths) {
+      const repoAbsPath = path.join(projectRoot, repoPath);
+      const repoName = path.basename(repoPath);
+      const worktreeDest = path.join(reposBase, repoName);
+
+      // Skip if worktree already exists
+      if (fs.existsSync(worktreeDest)) {
+        if (!skipped.includes(repoName)) skipped.push(repoName);
+        continue;
+      }
+
+      // Validate the source repo exists
+      if (!fs.existsSync(path.join(repoAbsPath, ".git"))) {
+        console.warn(`[orchestrator] Repo not found: ${repoPath}`);
+        if (!failed.includes(repoName)) failed.push(repoName);
+        continue;
+      }
+
+      try {
+        // Create feature branch if it doesn't exist
+        try {
+          execSync(`git -C "${repoAbsPath}" branch "${featureBranch}" 2>/dev/null || true`, { stdio: "pipe" });
+        } catch { /* branch may already exist */ }
+
+        // Create worktree
+        execSync(
+          `git -C "${repoAbsPath}" worktree add "${worktreeDest}" "${featureBranch}"`,
+          { stdio: "pipe", timeout: 30000 }
+        );
+        created.push(repoName);
+      } catch (err) {
+        // Try checking out existing branch
+        try {
+          execSync(
+            `git -C "${repoAbsPath}" worktree add "${worktreeDest}" -b "${featureBranch}" 2>/dev/null || git -C "${repoAbsPath}" worktree add "${worktreeDest}" "${featureBranch}"`,
+            { stdio: "pipe", timeout: 30000 }
+          );
+          created.push(repoName);
+        } catch (err2) {
+          console.error(`[orchestrator] Failed to create worktree for ${repoPath}:`, err2.message);
+          if (!failed.includes(repoName)) failed.push(repoName);
+        }
+      }
+    }
+
+    // Update signal tree with repos dir
+    const tree = this._signalTrees[feature.slug];
+    if (tree) {
+      tree.reposDir = reposBase;
+    }
+
+    // Post confirmation to feature channel
+    const parts = [];
+    if (scaffolded.length > 0) parts.push(`Scaffolded new: ${scaffolded.map(r => `\`${r}\``).join(", ")}`);
+    if (created.length > 0) parts.push(`Created worktrees: ${created.map(r => `\`${r}\``).join(", ")}`);
+    if (skipped.length > 0) parts.push(`Already exist: ${skipped.map(r => `\`${r}\``).join(", ")}`);
+    if (failed.length > 0) parts.push(`Failed: ${failed.map(r => `\`${r}\``).join(", ")}`);
+
+    await this.adapter.postPipelineMessage(feature.id,
+      `Repos pulled in for planning.\n${parts.join("\n")}\nWorktrees at: \`.features/${feature.slug}/repos/\``);
+
+    queries.insertEvent(feature.id, "system", "bridge",
+      `Repos pulled: ${[...scaffolded, ...created].join(", ")}${failed.length ? ` | failed: ${failed.join(", ")}` : ""}`);
+
+    console.log(`[orchestrator] ${feature.slug}: scaffolded=${scaffolded.length} created=${created.length} skipped=${skipped.length} failed=${failed.length}`);
+  }
+
+  // ─── Feature Completion ──────────────────────────────────────────────
+
+  async _handleFeatureComplete(slug) {
+    const feature = queries.getFeatureBySlug(slug);
+    if (!feature) return;
+
+    await this.adapter.postFeatureComplete(feature.id);
+
+    db.transaction(() => {
+      queries.updateFeaturePhase(feature.id, "complete");
+    });
+
+    this.supervisor.killFeature(feature.id);
+    this.fileIO.unwatchFeature(slug);
+    queries.insertEvent(feature.id, "feature-complete", "bridge", "All gates passed");
+    console.log(`[orchestrator] Feature ${slug} complete`);
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // FILE I/O SIGNAL HANDLERS
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  _setupFileIOHandlers() {
+    // Planning signals — now per-feature with { slug, role, filePath }
+    this.fileIO.on("planning:response", async ({ slug, role, filePath }) => {
+      try {
+        const content = readSignal(filePath, { deleteAfter: true });
+        if (!content) return;
+
+        const label = ROLE_LABELS[role] || role;
+        const feature = queries.getFeatureBySlug(slug);
+        if (!feature) return;
+
+        // Route through operator relay instead of posting directly
+        await this._enqueueForOperatorRelay(feature, label, "planning-response", content);
+        queries.insertEvent(feature.id, "agent-response", `agent:${role}`, content);
+      } catch (err) {
+        console.error("[orchestrator] Planning response error:", err.message);
+      }
+    });
+
+    this.fileIO.on("planning:question", async ({ slug, role, filePath }) => {
+      try {
+        const content = readSignal(filePath, { deleteAfter: true });
+        if (!content) return;
+
+        const label = ROLE_LABELS[role] || role;
+        const feature = queries.getFeatureBySlug(slug);
+        if (!feature) return;
+
+        // Route through operator relay instead of posting directly
+        const questionMsg = `*${feature.slug} / ${feature.active_planning_role} phase*\n\n${content}`;
+        await this._enqueueForOperatorRelay(feature, label, "planning-question", questionMsg);
+        queries.insertEvent(feature.id, "question", `agent:${role}`, content);
+      } catch (err) {
+        console.error("[orchestrator] Planning question error:", err.message);
+      }
+    });
+
+    this.fileIO.on("planning:done", async ({ slug, role, filePath }) => {
+      try {
+        await this._handlePlanningDone(slug, role, filePath);
+      } catch (err) {
+        console.error("[orchestrator] Planning done error:", err.message);
+      }
+    });
+
+    // Implementation signals — FL .agent-response routed through Operator relay
+    this.fileIO.on("impl:response", async ({ slug, agent, filePath }) => {
+      try {
+        const content = readSignal(filePath, { deleteAfter: true });
+        if (!content) return;
+        const feature = queries.getFeatureBySlug(slug);
+        if (!feature) return;
+        await this._enqueueForOperatorRelay(feature, "Feature Lead", "fl-response", content);
+      } catch (err) {
+        console.error("[orchestrator] Impl response error:", err.message);
+      }
+    });
+
+    // impl:operatorResponse — SOLE path to user for impl-phase agent output
+    this.fileIO.on("impl:operatorResponse", async ({ slug, filePath }) => {
+      try {
+        const content = readSignal(filePath, { deleteAfter: true });
+        if (!content) return;
+        const feature = queries.getFeatureBySlug(slug);
+        if (!feature) return;
+
+        // Parse structured blocks from Operator output
+        const parsed = parseOperatorResponse(content);
+
+        // Post the text content (with [DECISION] blocks stripped via parsed.plainText)
+        const textContent = parsed.plainText || content;
+        await this.adapter.postAgentResponse(feature.id, "Operator", textContent);
+
+        // Handle [DECISION] blocks — render as separate decision prompts.
+        // Skip any that duplicate a deferred decision (already queued by _requestPhaseReview).
+        for (const decision of parsed.decisions) {
+          if (this._deferredDecisions[feature.id]) {
+            const deferred = this._deferredDecisions[feature.id].decision;
+            if (deferred.id === decision.id) continue;
+          }
+          const options = decision.options.map(o => ({
+            id: o.id,
+            label: o.label,
+            style: o.style || "default",
+            description: o.description || "",
+          }));
+
+          // Start review session for gate decisions
+          let reviewUrl = null;
+          let qaUrl = null;
+          if (this.reviewSessions && decision.type === "approval" && decision.id.startsWith("gate-")) {
+            // Look for gate evidence HTML
+            const evidencePath = path.join(feature.signal_dir, "feature-lead", ".gate-evidence.html");
+            if (fs.existsSync(evidencePath)) {
+              reviewUrl = await this.reviewSessions.startDocReview(
+                decision.id, evidencePath, `Gate Evidence — ${decision.title}`, { featureId: feature.id }
+              );
+            }
+
+            // Read verification config from plan.yaml — start QA session if local-server
+            const verification = this._readVerificationConfig(feature);
+            if (verification && verification.type === "local-server" && verification.url) {
+              if (verification.command) {
+                // Start the dev server in the background
+                try {
+                  const featureReposDir = path.join(process.env.HOME, "src/iriai/.features", feature.slug, "repos");
+                  const proc = cpSpawn("sh", ["-c", verification.command], {
+                    cwd: featureReposDir,
+                    stdio: "ignore",
+                    detached: true,
+                  });
+                  proc.unref();
+                  // Brief wait for server startup
+                  await new Promise(r => setTimeout(r, 3000));
+                } catch (err) {
+                  console.error(`[orchestrator] Failed to start dev server for gate review:`, err.message);
+                }
+              }
+              qaUrl = await this.reviewSessions.startQaSession(
+                decision.id, verification.url, { featureId: feature.id }
+              );
+            }
+          }
+
+          const decResult = await this.adapter.postDecision(feature.id, {
+            id: decision.id,
+            title: decision.title,
+            context: decision.context,
+            type: decision.type || "approval",
+            options,
+            reviewUrl,
+            qaUrl,
+  
+          });
+
+          // Store in DB
+          queries.createDecision({
+            featureId: feature.id,
+            decisionId: decision.id,
+            decisionType: decision.type || "approval",
+            title: decision.title,
+            contextText: decision.context || null,
+            options,
+          });
+
+          // Store adapter-specific ref. Channel resolved from feature record.
+          const decChannel = feature.feature_channel || this.adapter.planningChannel;
+          queries.updateDecisionSlack(feature.id, decision.id, {
+            slackTs: decResult?.ref || null,
+            slackChannel: decChannel || null,
+            permalink: null,
+          });
+
+          // Gate decisions: set gate_evidence_ts
+          if (decision.type === "approval" && decision.id.startsWith("gate-")) {
+            queries.updateFeatureGateEvidenceTs(feature.id, decResult?.ref || null);
+          }
+        }
+
+        // Handle [RESOLVE_DECISION] blocks — Operator resolved a decision conversationally
+        for (const resolution of parsed.resolutions) {
+          const channel = feature.feature_channel || feature.slug;
+          const messageTs = `operator-${Date.now()}`;
+          try {
+            await this.handleDecisionClick(
+              resolution.id, resolution.option, "operator",
+              channel, messageTs, resolution.feedback || ""
+            );
+          } catch (err) {
+            console.error(`[orchestrator] Decision resolution error (${resolution.id}):`, err.message);
+          }
+        }
+
+        // Handle [ROUTE:agent_key] blocks
+        for (const route of parsed.routes) {
+          const targetAgent = queries.getAgentByKey(route.agentKey);
+          if (targetAgent) {
+            ensureDir(targetAgent.signal_dir);
+            writeSignal(path.join(targetAgent.signal_dir, SIGNAL.USER_MESSAGE), route.content);
+          }
+        }
+
+        // Resolve any pending relay waiter
+        this._resolveRelayWaiter(feature.id);
+      } catch (err) {
+        console.error("[orchestrator] Operator response error:", err.message);
+      }
+    });
+
+    this.fileIO.on("impl:featureComplete", async ({ slug }) => {
+      await this._handleFeatureComplete(slug);
+    });
+
+    this.fileIO.on("impl:phaseDone", ({ slug, filePath }) => {
+      // FL phase done — read signal and clean up
+      try { fs.unlinkSync(filePath); } catch { /* ok */ }
+      // The FL exit handler will spawn the next phase
+    });
+
+    this.fileIO.on("impl:contextRefresh", ({ slug, filePath }) => {
+      // FL context refresh — handled by supervisor exit handler
+      try { fs.unlinkSync(filePath); } catch { /* ok */ }
+    });
+
+    this.fileIO.on("impl:needsRestart", async ({ slug, dir, filePath }) => {
+      try {
+        const feature = queries.getFeatureBySlug(slug);
+        if (!feature) return;
+        // Find agent by signal dir
+        const agents = queries.getAgentsByFeature(feature.id);
+        const agent = agents.find(a => a.signal_dir === dir);
+        const agentLabel = agent?.role_name || "Agent";
+
+        await this.adapter.postPipelineMessage(feature.id,
+          `${agentLabel} restarting (context limit). Work preserved.`);
+        queries.insertEvent(feature.id, "system", "bridge", `${agentLabel} needs restart`);
+
+        // For planning roles: kill the agent so exit handler triggers retry with handover
+        if (agent && agent.agent_type === "planning-role") {
+          try { fs.unlinkSync(filePath); } catch { /* ok */ }
+          this.supervisor.kill(agent.agent_key);
+          // The exit handler (_handlePlanningRoleExit) will detect no .done and call
+          // scheduleRetry, which rebuilds the prompt with .handover file reference.
+        }
+      } catch (err) {
+        console.error("[orchestrator] Needs restart error:", err.message);
+      }
+    });
+
+    // Gate-ready: check if ALL teams are ready
+    this.fileIO.on("impl:gateReady", ({ slug, teamNum }) => {
+      const tree = this._signalTrees[slug];
+      if (!tree) return;
+
+      const allReady = Object.keys(tree.teams).every(tn =>
+        fs.existsSync(path.join(tree.teams[tn].orchestrator, SIGNAL.GATE_READY))
+      );
+
+      if (allReady) {
+        console.log(`[orchestrator] All teams gate-ready for ${slug}`);
+        this._triggerFeatureLead(slug, "gate-ready");
+      }
+    });
+
+    this.fileIO.on("impl:question", ({ slug, teamNum }) => {
+      const tree = this._signalTrees[slug];
+      if (!tree) return;
+
+      const questionTeams = Object.keys(tree.teams).filter(tn =>
+        fs.existsSync(path.join(tree.teams[tn].orchestrator, SIGNAL.QUESTION))
+      );
+      if (questionTeams.length > 0) {
+        this._triggerFeatureLead(slug, "question", { questionTeams });
+      }
+    });
+
+    this.fileIO.on("impl:crashed", ({ slug, teamNum }) => {
+      const tree = this._signalTrees[slug];
+      if (!tree) return;
+
+      const crashedTeams = Object.keys(tree.teams).filter(tn =>
+        fs.existsSync(path.join(tree.teams[tn].orchestrator, SIGNAL.CRASHED))
+      );
+      if (crashedTeams.length > 0) {
+        this._triggerFeatureLead(slug, "crash", { crashedTeams });
+      }
+    });
+
+    // Wire .task signals to orchestrators and role agents
+    this.fileIO.on("impl:orchTask", ({ slug, teamNum }) => {
+      const feature = queries.getFeatureBySlug(slug);
+      if (!feature) return;
+      const orchKey = `orch-${slug}-${teamNum}`;
+      const agent = queries.getAgentByKey(orchKey);
+      if (!agent) return;
+      this._handleOrchestratorTask(agent.id, feature, teamNum);
+    });
+
+    this.fileIO.on("impl:task", ({ slug, teamNum, role }) => {
+      const feature = queries.getFeatureBySlug(slug);
+      if (!feature) return;
+      const roleKey = `role-${slug}-${teamNum}-${role}`;
+      const agent = queries.getAgentByKey(roleKey);
+      if (!agent) return;
+      this._handleRoleTask(agent.id, feature);
+    });
+
+    // Operator user message
+    this.fileIO.on("impl:userMessage", ({ slug, agent: agentName }) => {
+      if (agentName !== "operator") return;
+      const feature = queries.getFeatureBySlug(slug);
+      if (!feature) return;
+      this._handleOperatorMessage(feature);
+    });
+
+    // Review agent done — route through Operator relay
+    this.fileIO.on("impl:done", async ({ slug, agent, role, filePath }) => {
+      if (!agent || !agent.startsWith("review-")) return;
+      try {
+        const feature = queries.getFeatureBySlug(slug);
+        if (!feature) return;
+
+        const outputPath = path.join(path.dirname(filePath), SIGNAL.OUTPUT);
+        const rawOutput = readSignal(outputPath);
+        if (!rawOutput) {
+          await this.adapter.postMessage(feature.id, `*[${role}]* Review complete (no output).`);
+          return;
+        }
+
+        queries.insertEvent(feature.id, "agent-response", `agent:${role}`, rawOutput);
+        await this._enqueueForOperatorRelay(feature, role, "review-completion", rawOutput);
+      } catch (err) {
+        console.error(`[orchestrator] Review done error for ${role}:`, err.message);
+      }
+    });
+
+    // Operator .needs-repos — create worktrees for requested repos
+    this.fileIO.on("impl:needsRepos", async ({ slug, filePath }) => {
+      try {
+        const content = readSignal(filePath, { deleteAfter: true });
+        if (!content) return;
+        const feature = queries.getFeatureBySlug(slug);
+        if (!feature) return;
+
+        await this._handleNeedsRepos(feature, content);
+      } catch (err) {
+        console.error("[orchestrator] Needs repos error:", err.message);
+      }
+    });
+  }
+
+  _triggerFeatureLead(slug, trigger, opts = {}) {
+    const feature = queries.getFeatureBySlug(slug);
+    if (!feature) return;
+    const flKey = `fl-${slug}`;
+    const flAgent = queries.getAgentByKey(flKey);
+    if (!flAgent) return;
+
+    const tree = this._signalTrees[slug];
+    if (!tree) return;
+
+    // If FL is already running, send trigger as a .user-message instead of killing it
+    if (this.supervisor.isRunning(flKey)) {
+      const msg = trigger === "gate-ready"
+        ? "TRIGGER: All teams have signaled gate-ready. Begin gate review."
+        : trigger === "question"
+        ? `TRIGGER: Teams ${(opts.questionTeams || []).join(", ")} have questions needing resolution.`
+        : trigger === "crash"
+        ? `TRIGGER: Teams ${(opts.crashedTeams || []).join(", ")} have crashed orchestrators. Handle recovery.`
+        : `TRIGGER: ${trigger}`;
+      writeSignal(path.join(tree.featureLead, SIGNAL.USER_MESSAGE), msg);
+      return;
+    }
+
+    // FL not running — spawn in trigger mode
+    this._spawnFeatureLead(flAgent.id, feature, tree, "trigger", {
+      trigger,
+      ...opts,
+    });
+  }
+
+  _handleOrchestratorTask(agentId, feature, teamNum) {
+    const agent = queries.getAgentById(agentId);
+    if (!agent) return;
+    const tree = this._signalTrees[feature.slug];
+    if (!tree) return;
+    const team = tree.teams[teamNum];
+    if (!team) return;
+
+    // Read and consume .task
+    const taskFile = path.join(team.orchestrator, SIGNAL.TASK);
+    const task = readSignal(taskFile, { deleteAfter: true });
+    if (!task) return;
+
+    // Clean previous signals
+    for (const sig of [SIGNAL.DONE, SIGNAL.GATE_READY, SIGNAL.CRASHED, SIGNAL.GATE_APPROVED, SIGNAL.QUESTION, SIGNAL.ANSWER]) {
+      try { fs.unlinkSync(path.join(team.orchestrator, sig)); } catch { /* ok */ }
+    }
+
+    // Resolve team-specific repos directory for branch isolation
+    const teamReposDir = path.join(process.env.HOME, "src/iriai/.features", feature.slug, "teams", String(teamNum), "repos");
+    const prompt = buildOrchestratorPrompt({
+      teamDir: team.dir,
+      orchDir: team.orchestrator,
+      task,
+      teamReposDir: fs.existsSync(teamReposDir) ? teamReposDir : null,
+    });
+
+    this.supervisor.spawn(agentId, prompt);
+    queries.insertEvent(feature.id, "agent-started", "bridge", `Team ${teamNum} orchestrator dispatched`);
+  }
+
+  _handleRoleTask(agentId, feature) {
+    const agent = queries.getAgentById(agentId);
+    if (!agent) return;
+
+    // Atomic rename: .task → .active-task
+    const taskFile = path.join(agent.signal_dir, SIGNAL.TASK);
+    const activeFile = path.join(agent.signal_dir, SIGNAL.ACTIVE_TASK);
+    let task;
+    try {
+      fs.renameSync(taskFile, activeFile);
+      task = fs.readFileSync(activeFile, "utf-8").trim();
+    } catch {
+      task = readSignal(taskFile, { deleteAfter: true });
+    }
+    if (!task) return;
+
+    // Clean previous signals
+    for (const sig of [SIGNAL.DONE, SIGNAL.CRASHED]) {
+      try { fs.unlinkSync(path.join(agent.signal_dir, sig)); } catch { /* ok */ }
+    }
+
+    const prompt = buildRolePrompt({
+      role: agent.role_name,
+      signalDir: agent.signal_dir,
+      task,
+    });
+
+    this.supervisor.spawn(agentId, prompt);
+    queries.insertEvent(feature.id, "agent-started", "bridge", `Role ${agent.role_name} (team ${agent.team_num}) dispatched`);
+  }
+
+  async _handleOperatorMessage(feature) {
+    const opKey = `op-${feature.slug}`;
+    const opAgent = queries.getAgentByKey(opKey);
+    if (!opAgent) return;
+
+    const tree = this._signalTrees[feature.slug];
+    if (!tree?.operator) return;
+
+    // Read user message
+    const msgPath = path.join(tree.operator, SIGNAL.USER_MESSAGE);
+    const userMessage = readSignal(msgPath, { deleteAfter: true });
+    if (!userMessage) return;
+
+    // Invoke ephemeral operator with planning-phase context
+    const planDir = tree.plansDir || path.join(tree.featureDir, "plans");
+    try {
+      await invokeOperator({
+        feature,
+        operatorDir: tree.operator,
+        flDir: tree.featureLead,
+        featureDir: tree.featureDir,
+        userMessage,
+        supervisor: this.supervisor,
+        agentId: opAgent.id,
+        planDir,
+        activePlanningRole: feature.active_planning_role,
+      });
+    } catch (err) {
+      console.error("[orchestrator] Operator invocation error:", err.message);
+      // Fallback: write raw message to active agent
+      if (tree.featureLead) {
+        writeSignal(path.join(tree.featureLead, SIGNAL.USER_MESSAGE), userMessage);
+      } else if (feature.active_planning_role && tree.planning?.[feature.active_planning_role]) {
+        writeSignal(path.join(tree.planning[feature.active_planning_role], SIGNAL.USER_MESSAGE), userMessage);
+      }
+    }
+  }
+
+  /**
+   * Handle operator exit — retry on failure (e.g. "Prompt is too long").
+   * On success (exit 0), reset to idle.
+   */
+  _handleOperatorExit(agentId, feature, exitCode, elapsed) {
+    if (exitCode === 0) {
+      queries.updateAgentStatus(agentId, "idle");
+      queries.resetAgentRetry(agentId);
+      return;
+    }
+
+    // Non-zero exit — schedule retry via supervisor (respects max_retries)
+    const tree = this._signalTrees[feature.slug];
+    if (!tree) {
+      queries.updateAgentStatus(agentId, "crashed");
+      return;
+    }
+
+    console.log(`[orchestrator] Operator exited with code ${exitCode} after ${elapsed}ms — scheduling retry`);
+
+    const retried = this.supervisor.scheduleRetry(agentId, () => {
+      // On retry, assembleHistory will re-summarize with a tighter budget
+      return { prompt: "Re-read your CLAUDE.md and check for pending relay queue items or user messages. Write a status update to .agent-response if there's nothing to relay.", continue: false };
+    });
+
+    if (!retried) {
+      queries.updateAgentStatus(agentId, "idle");
+      console.error(`[orchestrator] Operator for ${feature.slug} exhausted retries — resetting to idle`);
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // SUPERVISOR EVENT HANDLERS
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  _setupSupervisorHandlers() {
+    this.supervisor.on("agent:exit", (info) => {
+      this._handleAgentExit(info);
+    });
+
+    this.supervisor.on("agent:crashed", async (info) => {
+      const feature = queries.getFeatureById(info.featureId);
+      if (!feature) return;
+      await this.adapter.postPipelineMessage(feature.id,
+        `Agent ${info.agentKey} crashed after ${info.retryCount} retries.`);
+      queries.insertEvent(info.featureId, "agent-crashed", "bridge",
+        `${info.agentKey} crashed after ${info.retryCount} retries`);
+    });
+  }
+
+  _handleAgentExit({ agentId, agentKey, agentType, featureId, exitCode, elapsed, signalDir, roleName, teamNum }) {
+    const feature = queries.getFeatureById(featureId);
+    if (!feature) return;
+
+    switch (agentType) {
+      case "planning-role":
+        this._handlePlanningRoleExit(agentId, feature, signalDir, roleName);
+        break;
+      case "feature-lead":
+        this._handleFeatureLeadExit(agentId, feature, signalDir, elapsed);
+        break;
+      case "team-orchestrator":
+        this._handleOrchestratorExit(agentId, feature, signalDir, teamNum, elapsed);
+        break;
+      case "role-agent":
+      case "review-agent":
+        this._handleRoleExit(agentId, feature, signalDir, roleName, elapsed);
+        break;
+      case "operator":
+        this._handleOperatorExit(agentId, feature, exitCode, elapsed);
+        break;
+    }
+  }
+
+  _handlePlanningRoleExit(agentId, feature, signalDir, roleName) {
+    const doneFile = path.join(signalDir, SIGNAL.DONE);
+    if (fs.existsSync(doneFile)) {
+      queries.updateAgentStatus(agentId, "done");
+      this._handlePlanningDone(feature.slug, roleName, doneFile);
+      return;
+    }
+
+    // Check if the file watcher already processed .done (it deletes the file).
+    // If review gate is posted or agent already marked done, don't retry.
+    const meta = queries.getFeatureMetadata(feature.id);
+    const agent = queries.getAgentById(agentId);
+    if (meta.awaiting_phase_review && meta.phase_review_role === roleName) {
+      console.log(`[orchestrator] ${roleName} exit: review gate already posted, skipping retry`);
+      queries.updateAgentStatus(agentId, "done");
+      return;
+    }
+    if (agent && agent.status === "done") {
+      console.log(`[orchestrator] ${roleName} exit: already marked done, skipping retry`);
+      return;
+    }
+    // Also skip if phase has already advanced past this role
+    if (feature.active_planning_role && feature.active_planning_role !== roleName) {
+      console.log(`[orchestrator] ${roleName} exit: phase already advanced to ${feature.active_planning_role}, skipping retry`);
+      queries.updateAgentStatus(agentId, "done");
+      return;
+    }
+
+    {
+      // Retry with file-based handover reference (never embed content inline)
+      const featureDir = feature.signal_dir;
+      const planDir = path.join(featureDir, "plans");
+      const reposDir = path.join(process.env.HOME, "src/iriai/.features", feature.slug, "repos");
+
+      // Check if plan artifacts are large enough to warrant summarization
+      const artifactStats = this._getPlanArtifactStats(planDir);
+      const needsSummary = artifactStats.totalKB > ARTIFACT_SUMMARY_THRESHOLD_KB;
+
+      if (needsSummary) {
+        // Run summarizer first, then retry the planning role on completion
+        console.log(`[orchestrator] ${roleName}: plan artifacts are ${artifactStats.totalKB} KB — running summarizer before retry`);
+        this._runArtifactSummarizer(feature, planDir, signalDir, artifactStats, () => {
+          this._schedulePlanningRetry(agentId, feature, signalDir, planDir, featureDir, reposDir, roleName);
+        });
+      } else {
+        this._schedulePlanningRetry(agentId, feature, signalDir, planDir, featureDir, reposDir, roleName);
+      }
+    }
+  }
+
+  /**
+   * Ensure a mockup review session exists and inject its URL into design-decisions.md.
+   * Used by both _requestPhaseReview (fresh) and repostPendingPhaseReview (recovery).
+   */
+  async _ensureMockupSession(planDir, mockupDecisionId, featureId) {
+    const mockupPath = path.join(planDir, "mockup.html");
+    if (!fs.existsSync(mockupPath)) return;
+
+    // Try restore first, then start fresh
+    let mockupUrl = await this.reviewSessions.restoreSession(mockupDecisionId);
+    if (!mockupUrl) {
+      mockupUrl = await this.reviewSessions.startMockupReview(
+        mockupDecisionId, mockupPath, { featureId }
+      );
+    }
+    if (!mockupUrl) return;
+
+    // Inject mockup URL into design-decisions.md (strip stale ones first)
+    const designDocPath = findArtifact("design-decisions", planDir);
+    if (!designDocPath) return;
+
+    let content = fs.readFileSync(designDocPath, "utf-8");
+    content = content.replace(/\n+---\n+## Interactive Mockup\n+\*\*\[View UI Mockup in Browser\]\(http[^)]*\)\*\*\n+[^\n]*\n*/g, "");
+
+    const section = `\n\n---\n\n## Interactive Mockup\n\n**[View UI Mockup in Browser](${mockupUrl})**\n\nOpen the link above to see the HTML/CSS mockup with annotation tools.\n`;
+    const overviewEnd = content.indexOf("\n---", content.indexOf("## Overview"));
+    if (overviewEnd > 0) {
+      fs.writeFileSync(designDocPath, content.slice(0, overviewEnd) + section + content.slice(overviewEnd), "utf-8");
+    } else {
+      const firstHeadingEnd = content.indexOf("\n", content.indexOf("# "));
+      if (firstHeadingEnd > 0) {
+        fs.writeFileSync(designDocPath, content.slice(0, firstHeadingEnd + 1) + section + content.slice(firstHeadingEnd + 1), "utf-8");
+      } else {
+        fs.writeFileSync(designDocPath, section + "\n" + content, "utf-8");
+      }
+    }
+  }
+
+  /**
+   * Schedule a planning role retry (extracted for use with/without summarizer).
+   */
+  _schedulePlanningRetry(agentId, feature, signalDir, planDir, featureDir, reposDir, roleName) {
+    const summaryPath = path.join(planDir, ARTIFACT_SUMMARY_FILE);
+    const hasSummary = fs.existsSync(summaryPath);
+
+    const retried = this.supervisor.scheduleRetry(agentId, (agent) => {
+      const hasHandover = fs.existsSync(path.join(signalDir, SIGNAL.HANDOVER));
+
+      const taskHeader = [
+        `SLACK_MODE=true`,
+        `FEATURE_SLUG=${feature.slug}`,
+        `SIGNAL_DIR=${signalDir}`,
+        `PLAN_DIR=${planDir}`,
+        `FEATURE_DIR=${featureDir}`,
+        `REPOS_DIR=${reposDir}`,
+      ].join("\n");
+
+      let handoverRef;
+      if (hasHandover) {
+        handoverRef = `\nCONTINUATION: Read ${signalDir}/.handover for your previous session's context. Resume from where it left off.\n`;
+      } else {
+        handoverRef = `\nRETRY ${agent.retry_count}: Previous session crashed. Check git status/diff for completed work. Do NOT redo completed work.\n`;
+      }
+
+      // If summarizer produced a summary, tell the agent to use it instead of re-reading full artifacts
+      if (hasSummary) {
+        handoverRef += `
+ARTIFACT SUMMARY AVAILABLE: A compressed summary of your plan artifacts exists at:
+  ${summaryPath}
+
+Read this summary FIRST to restore context efficiently. It preserves component hierarchies,
+state tables, test IDs, and flow names while compressing prose and visual specs.
+Only read full artifact files (design-decisions.md, PRD, mockup.html) when you need to
+modify a SPECIFIC section — never re-read them in full.\n`;
+      }
+
+      const prompt = buildPlanningRolePrompt({
+        task: taskHeader + handoverRef,
+        signalDir,
+        featureSlug: feature.slug,
+      });
+
+      return { prompt, continue: !hasHandover };
+    });
+    if (!retried) {
+      queries.insertEvent(feature.id, "agent-crashed", "bridge", `Planning role ${roleName} crashed`);
+    }
+  }
+
+  /**
+   * Get size stats for plan directory artifacts.
+   */
+  _getPlanArtifactStats(planDir) {
+    const result = { totalKB: 0, artifacts: [] };
+    if (!fs.existsSync(planDir)) return result;
+
+    const ARTIFACT_EXTENSIONS = new Set([".md", ".html", ".json", ".yaml", ".yml"]);
+    try {
+      for (const name of fs.readdirSync(planDir)) {
+        // Skip the summary file itself and hidden files
+        if (name === ARTIFACT_SUMMARY_FILE || name.startsWith(".")) continue;
+        const ext = path.extname(name).toLowerCase();
+        if (!ARTIFACT_EXTENSIONS.has(ext)) continue;
+
+        const filePath = path.join(planDir, name);
+        const stat = fs.statSync(filePath);
+        if (!stat.isFile()) continue;
+
+        const sizeKB = Math.round(stat.size / 1024);
+        // Estimate line count for large files to avoid reading them into memory
+        let lines;
+        if (stat.size > 100 * 1024) {
+          lines = Math.round(stat.size / 80); // ~80 bytes/line estimate
+        } else {
+          lines = fs.readFileSync(filePath, "utf-8").split("\n").length;
+        }
+        result.artifacts.push({ name, sizeKB, lines, path: filePath });
+        result.totalKB += sizeKB;
+      }
+    } catch { /* ok — dir might be gone */ }
+
+    return result;
+  }
+
+  /**
+   * Spawn a fast summarizer agent (sonnet) to compress plan artifacts before restart.
+   * Calls onComplete when done (whether success or failure — we retry either way).
+   */
+  _runArtifactSummarizer(feature, planDir, roleSignalDir, artifactStats, onComplete) {
+    const summarizerDir = path.join(roleSignalDir, ".summarizer");
+    ensureDir(summarizerDir);
+
+    const outputPath = path.join(planDir, ARTIFACT_SUMMARY_FILE);
+
+    const prompt = buildArtifactSummarizerPrompt({
+      planDir,
+      outputPath,
+      artifacts: artifactStats.artifacts,
+    });
+
+    // Spawn directly via AgentProcess (no DB record needed — this is ephemeral)
+    const proc = new AgentProcess({
+      key: `summarizer-${feature.slug}`,
+      cwd: planDir,
+      extraEnv: {},
+      signalDir: summarizerDir,
+    });
+
+    proc.spawnClaude(prompt, { model: SUMMARIZER_MODEL });
+    queries.insertEvent(feature.id, "summarizer-started", "bridge",
+      `Artifact summarizer dispatched (${artifactStats.totalKB} KB across ${artifactStats.artifacts.length} files)`);
+
+    // Timeout fallback — don't let a stuck summarizer block the retry forever
+    const timer = setTimeout(() => {
+      console.log(`[orchestrator] Summarizer timed out for ${feature.slug} — proceeding with retry`);
+      proc.kill();
+      onComplete();
+    }, SUMMARIZER_TIMEOUT_MS);
+
+    proc.on("exit", ({ exitCode }) => {
+      clearTimeout(timer);
+
+      if (exitCode === 0 && fs.existsSync(outputPath)) {
+        const summarySize = Math.round(fs.statSync(outputPath).size / 1024);
+        console.log(`[orchestrator] Summarizer complete for ${feature.slug}: ${summarySize} KB summary (from ${artifactStats.totalKB} KB artifacts)`);
+        queries.insertEvent(feature.id, "summarizer-done", "bridge",
+          `Artifact summary written: ${summarySize} KB (compressed from ${artifactStats.totalKB} KB)`);
+      } else {
+        console.log(`[orchestrator] Summarizer failed for ${feature.slug} (exit ${exitCode}) — proceeding without summary`);
+      }
+
+      // Clean up ephemeral summarizer dir
+      try { fs.rmSync(summarizerDir, { recursive: true, force: true }); } catch { /* ok */ }
+
+      onComplete();
+    });
+  }
+
+  _handleFeatureLeadExit(agentId, feature, signalDir, elapsed) {
+    const tree = this._signalTrees[feature.slug];
+    if (!tree) return;
+
+    // Check signals in priority order
+    const completeFile = path.join(signalDir, SIGNAL.FEATURE_COMPLETE);
+    if (fs.existsSync(completeFile)) {
+      queries.updateAgentStatus(agentId, "done");
+      this._handleFeatureComplete(feature.slug);
+      return;
+    }
+
+    const refreshFile = path.join(signalDir, SIGNAL.CONTEXT_REFRESH);
+    if (fs.existsSync(refreshFile)) {
+      try { fs.unlinkSync(refreshFile); } catch { /* ok */ }
+      // Read handover if available
+      const handoverFile = path.join(signalDir, SIGNAL.HANDOVER);
+      const handoverContent = readSignal(handoverFile, { deleteAfter: true });
+      queries.resetAgentRetry(agentId);
+      this._spawnFeatureLead(agentId, feature, tree, "refresh", { handoverContent });
+      return;
+    }
+
+    const phaseDoneFile = path.join(signalDir, SIGNAL.PHASE_DONE);
+    if (fs.existsSync(phaseDoneFile)) {
+      try { fs.unlinkSync(phaseDoneFile); } catch { /* ok */ }
+      // Phase complete — spawn refresh for next phase
+      queries.resetAgentRetry(agentId);
+      this._spawnFeatureLead(agentId, feature, tree, "refresh");
+      return;
+    }
+
+    const needsRestartFile = path.join(signalDir, SIGNAL.NEEDS_RESTART);
+    if (fs.existsSync(needsRestartFile)) {
+      try { fs.unlinkSync(needsRestartFile); } catch { /* ok */ }
+      const handoverContent = readSignal(path.join(signalDir, SIGNAL.HANDOVER), { deleteAfter: true });
+      queries.resetAgentRetry(agentId);
+      this._spawnFeatureLead(agentId, feature, tree, "refresh", { handoverContent });
+      return;
+    }
+
+    // Guard: file watcher may have already processed signals and deleted them.
+    // If agent is already marked done, don't retry.
+    const agentState = queries.getAgentById(agentId);
+    if (agentState && agentState.status === "done") {
+      console.log(`[orchestrator] FL exit: already marked done, skipping retry`);
+      return;
+    }
+
+    // Auto-refresh if ran long enough (context exhaustion)
+    if (elapsed >= FL_CONTEXT_EXHAUST_MS) {
+      queries.resetAgentRetry(agentId);
+      this._spawnFeatureLead(agentId, feature, tree, "refresh");
+      return;
+    }
+
+    // Otherwise crash — try retry with --continue (conversation is intact, just process died)
+    const retried = this.supervisor.scheduleRetry(agentId, () => {
+      const prompt = buildFeatureLeadRefreshPrompt({
+        featureName: feature.slug,
+        numTeams: Object.keys(tree.teams).length || feature.num_teams,
+        teamSignalBase: path.join(tree.featureDir, "teams"),
+        planReadInstruction: this._resolvePlanInstruction(tree.featureLead, tree.featureDir),
+        featureLeadDir: tree.featureLead,
+        featureReviewDir: path.join(tree.featureDir, "feature-review"),
+        dashboardLog: path.join(tree.featureDir, ".dashboard-log"),
+        gateEvidenceTs: feature.gate_evidence_ts,
+        featureDir: tree.featureDir,
+      });
+      return { prompt, continue: true };
+    });
+
+    if (!retried) {
+      // Max retries exhausted — stop and notify
+      queries.updateAgentStatus(agentId, "idle");
+      this.adapter.postPipelineMessage(feature.id,
+        `Feature Lead exhausted all retries. Waiting for operator or user intervention. Use "restart FL" to retry.`).catch(() => {});
+      queries.insertEvent(feature.id, "agent-crashed", "bridge", "Feature Lead exhausted max retries, stopped.");
+    }
+  }
+
+  _handleOrchestratorExit(agentId, feature, signalDir, teamNum, elapsed) {
+    const gateReadyFile = path.join(signalDir, SIGNAL.GATE_READY);
+    const doneFile = path.join(signalDir, SIGNAL.DONE);
+
+    if (fs.existsSync(gateReadyFile) || fs.existsSync(doneFile)) {
+      queries.updateAgentStatus(agentId, "done");
+      return;
+    }
+
+    const needsRestartFile = path.join(signalDir, SIGNAL.NEEDS_RESTART);
+    if (fs.existsSync(needsRestartFile)) {
+      try { fs.unlinkSync(needsRestartFile); } catch { /* ok */ }
+      // Don't count as crash
+      queries.updateAgentStatus(agentId, "idle");
+      return;
+    }
+
+    // Guard: file watcher may have already processed signals and deleted them.
+    const agentState = queries.getAgentById(agentId);
+    if (agentState && agentState.status === "done") {
+      console.log(`[orchestrator] Orch-${teamNum} exit: already marked done, skipping retry`);
+      return;
+    }
+
+    // Retry
+    const tree = this._signalTrees[feature.slug];
+    const team = tree?.teams[teamNum];
+    if (!team) return;
+
+    const teamReposDir = path.join(process.env.HOME, "src/iriai/.features", feature.slug, "teams", String(teamNum), "repos");
+    this.supervisor.scheduleRetry(agentId, () => {
+      const prompt = buildOrchestratorPrompt({
+        teamDir: team.dir,
+        orchDir: team.orchestrator,
+        task: "Resume from where you left off. Read HANDOVER.md and STEP-SUMMARY.md for progress.",
+        recoveryContext: { retryCount: queries.getAgentById(agentId).retry_count },
+        teamReposDir: fs.existsSync(teamReposDir) ? teamReposDir : null,
+      });
+      // Crash recovery — use --continue to resume the conversation
+      return { prompt, continue: true };
+    });
+  }
+
+  _handleRoleExit(agentId, feature, signalDir, roleName, elapsed) {
+    const doneFile = path.join(signalDir, SIGNAL.DONE);
+    if (fs.existsSync(doneFile)) {
+      queries.updateAgentStatus(agentId, "done");
+      return;
+    }
+
+    // Guard: file watcher may have already processed .done and deleted it.
+    const agentState = queries.getAgentById(agentId);
+    if (agentState && agentState.status === "done") {
+      console.log(`[orchestrator] Role ${roleName} exit: already marked done, skipping retry`);
+      return;
+    }
+
+    const needsRestartFile = path.join(signalDir, SIGNAL.NEEDS_RESTART);
+    if (fs.existsSync(needsRestartFile)) {
+      try { fs.unlinkSync(needsRestartFile); } catch { /* ok */ }
+      const handoverContent = readSignal(path.join(signalDir, SIGNAL.HANDOVER), { deleteAfter: true });
+      queries.resetAgentRetry(agentId);
+      // Re-spawn with handover
+      const prompt = buildRolePrompt({
+        role: roleName,
+        signalDir,
+        task: "Resume from handover context.",
+        recoveryContext: handoverContent ? { type: "handover", content: handoverContent } : null,
+      });
+      this.supervisor.spawn(agentId, prompt);
+      return;
+    }
+
+    // Retry with crash recovery context — use --continue to resume conversation
+    this.supervisor.scheduleRetry(agentId, (agent) => {
+      const prompt = buildRolePrompt({
+        role: roleName,
+        signalDir,
+        task: "Resume from where you left off.",
+        recoveryContext: { type: "crash", retryCount: agent.retry_count },
+      });
+      return { prompt, continue: true };
+    });
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // OPERATOR RELAY QUEUE
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Enqueue agent output for formatting by the Operator before posting to the user.
+   */
+  async _enqueueForOperatorRelay(feature, sourceAgent, eventHint, rawContent) {
+    queries.insertRelayEntry({
+      featureId: feature.id,
+      sourceAgent,
+      eventHint,
+      rawContent,
+    });
+
+    // Kick the serial queue processor
+    this._processRelayQueue(feature.id);
+  }
+
+  /**
+   * Serial queue processor per feature. Only one relay processes at a time.
+   */
+  async _processRelayQueue(featureId) {
+    if (this._relayProcessing[featureId]) return;
+    this._relayProcessing[featureId] = true;
+
+    try {
+      let entry;
+      while ((entry = queries.getNextPendingRelay(featureId))) {
+        await this._invokeOperatorRelayAndWait(featureId, entry);
+      }
+    } catch (err) {
+      console.error("[orchestrator] Relay queue error:", err.message);
+    } finally {
+      delete this._relayProcessing[featureId];
+    }
+  }
+
+  /**
+   * Invoke Operator for a single relay entry. Returns a promise that resolves when
+   * impl:operatorResponse fires (marking posted) or on timeout (fallback direct post).
+   */
+  async _invokeOperatorRelayAndWait(featureId, queueEntry) {
+    const feature = queries.getFeatureById(featureId);
+    if (!feature) return;
+
+    const tree = this._signalTrees[feature.slug];
+    if (!tree?.operator) {
+      // No operator dir — fallback to direct post
+      await this._fallbackDirectPost(feature, queueEntry.source_agent, queueEntry.raw_content, queueEntry.id, queueEntry.event_hint);
+      return;
+    }
+
+    const opKey = `op-${feature.slug}`;
+    const opAgent = queries.getAgentByKey(opKey);
+    if (!opAgent) {
+      await this._fallbackDirectPost(feature, queueEntry.source_agent, queueEntry.raw_content, queueEntry.id, queueEntry.event_hint);
+      return;
+    }
+
+    // Mark as processing
+    queries.updateRelayStatus(queueEntry.id, "processing");
+
+    // Kill any existing operator session (shared key)
+    this.supervisor.kill(opKey);
+
+    try {
+      await new Promise((resolve, reject) => {
+        // Store the waiter so impl:operatorResponse can resolve it
+        this._relayWaiters[featureId] = { resolve, queueId: queueEntry.id };
+
+        // Set timeout for fallback
+        const timer = setTimeout(() => {
+          console.warn(`[orchestrator] Operator relay timed out for queue ${queueEntry.id}`);
+          delete this._relayWaiters[featureId];
+          this._fallbackDirectPost(feature, queueEntry.source_agent, queueEntry.raw_content, queueEntry.id, queueEntry.event_hint)
+            .then(resolve)
+            .catch(reject);
+        }, OPERATOR_RELAY_TIMEOUT_MS);
+
+        this._relayWaiters[featureId].timer = timer;
+
+        // Spawn the Operator in relay mode (--continue if it has a prior session)
+        const opHasSession = opAgent.started_at != null;
+        invokeOperatorRelay({
+          feature,
+          queueEntry,
+          supervisor: this.supervisor,
+          agentId: opAgent.id,
+          operatorDir: tree.operator,
+          featureDir: tree.featureDir,
+          continue: opHasSession,
+        }).catch(err => {
+          console.error("[orchestrator] Operator relay spawn error:", err.message);
+          clearTimeout(timer);
+          delete this._relayWaiters[featureId];
+          this._fallbackDirectPost(feature, queueEntry.source_agent, queueEntry.raw_content, queueEntry.id, queueEntry.event_hint)
+            .then(resolve)
+            .catch(reject);
+        });
+      });
+    } catch (err) {
+      console.error("[orchestrator] Relay wait error:", err.message);
+    }
+  }
+
+  /**
+   * Resolve a pending relay waiter (called when impl:operatorResponse fires).
+   */
+  _resolveRelayWaiter(featureId) {
+    const waiter = this._relayWaiters[featureId];
+    if (!waiter) return;
+
+    clearTimeout(waiter.timer);
+    // Mark queue entry as posted
+    queries.updateRelayStatus(waiter.queueId, "posted", { processedAt: new Date().toISOString() });
+    delete this._relayWaiters[featureId];
+    waiter.resolve();
+
+    // Post any deferred decision now that the Operator message is visible
+    this._postDeferredDecision(featureId);
+  }
+
+  /**
+   * Post a deferred decision (stored by _requestPhaseReview) after the Operator
+   * relay completes, so the decision buttons appear after the Operator's message.
+   */
+  async _postDeferredDecision(featureId) {
+    const deferred = this._deferredDecisions[featureId];
+    if (!deferred) return;
+    delete this._deferredDecisions[featureId];
+
+    try {
+      await this.adapter.postDecision(deferred.featureId, deferred.decision);
+    } catch (err) {
+      console.error("[orchestrator] Failed to post deferred decision:", err.message);
+    }
+  }
+
+  /**
+   * Fallback: post raw agent content directly when Operator fails or times out.
+   * @param {string} eventHint - optional hint from the relay entry
+   */
+  async _fallbackDirectPost(feature, sourceAgent, rawContent, queueId, eventHint) {
+    // For decision-needed relays: skip text fallback but post the deferred decision
+    if (eventHint === "decision-needed") {
+      console.log(`[orchestrator] Operator relay timed out for decision-needed (queue ${queueId}) — posting decision directly`);
+      queries.updateRelayStatus(queueId, "posted", { processedAt: new Date().toISOString() });
+      await this._postDeferredDecision(feature.id);
+      return;
+    }
+
+    console.warn(`[orchestrator] Fallback direct post for ${sourceAgent} (queue ${queueId})`);
+    try {
+      await this.adapter.postAgentResponse(feature.id, sourceAgent, rawContent);
+      queries.updateRelayStatus(queueId, "posted", { processedAt: new Date().toISOString() });
+    } catch (err) {
+      console.error("[orchestrator] Fallback post error:", err.message);
+      queries.updateRelayStatus(queueId, "failed");
+      queries.incrementRelayRetry(queueId);
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // STALE SIGNAL SAFETY NET
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  startStaleScan() {
+    this._staleScanTimer = setInterval(() => this._scanForStaleSignals(), STALE_SCAN_INTERVAL_MS);
+    this._staleScanTimer.unref();
+  }
+
+  _scanForStaleSignals() {
+    for (const [slug, tree] of Object.entries(this._signalTrees)) {
+      const feature = queries.getFeatureBySlug(slug);
+      if (!feature || feature.phase === "complete" || feature.phase === "failed") continue;
+
+      // Check for stale gate-ready — skip if FL already running or gate evidence already posted
+      const flAgent = queries.getAgentByKey(`fl-${slug}`);
+      const flRunning = flAgent && (flAgent.status === "running" || this.supervisor.isRunning(`fl-${slug}`));
+      if (!flRunning && !feature.gate_evidence_ts) {
+        const allReady = Object.keys(tree.teams).every(tn =>
+          tree.teams[tn].orchestrator && fs.existsSync(path.join(tree.teams[tn].orchestrator, SIGNAL.GATE_READY))
+        );
+        if (allReady && Object.keys(tree.teams).length > 0) {
+          console.log(`[orchestrator] Stale scan: all teams gate-ready for ${slug}`);
+          this._triggerFeatureLead(slug, "gate-ready");
+          continue;
+        }
+      }
+
+      // Check for stale questions
+      const questionTeams = Object.keys(tree.teams).filter(tn =>
+        tree.teams[tn].orchestrator && fs.existsSync(path.join(tree.teams[tn].orchestrator, SIGNAL.QUESTION))
+      );
+      if (questionTeams.length > 0) {
+        console.log(`[orchestrator] Stale scan: questions pending for ${slug}`);
+        this._triggerFeatureLead(slug, "question", { questionTeams });
+        continue;
+      }
+
+      // Check for stale crashes
+      const crashedTeams = Object.keys(tree.teams).filter(tn =>
+        tree.teams[tn].orchestrator && fs.existsSync(path.join(tree.teams[tn].orchestrator, SIGNAL.CRASHED))
+      );
+      if (crashedTeams.length > 0) {
+        console.log(`[orchestrator] Stale scan: crashes pending for ${slug}`);
+        this._triggerFeatureLead(slug, "crash", { crashedTeams });
+      }
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // SHUTDOWN
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  async shutdown() {
+    if (this._staleScanTimer) {
+      clearInterval(this._staleScanTimer);
+      this._staleScanTimer = null;
+    }
+    if (this.reviewSessions) {
+      await this.reviewSessions.stopAll();
+    }
+    await this.supervisor.shutdown();
+    await this.fileIO.closeAll();
+  }
+}