iriai-build 0.1.0

package/lib/state-machines/feature-lead.js

@@ -0,0 +1,408 @@
+// feature-lead.js — Multi-phase Feature Lead orchestrator.
+// Replaces run-feature-lead.sh. One AgentProcess at a time, fresh per phase/trigger.
+//
+// INIT → DISPATCHING → MONITORING → HANDLING_TRIGGER → GATE_REVIEW → MONITORING → ... → COMPLETE
+
+import { EventEmitter } from "node:events";
+import fs from "node:fs";
+import path from "node:path";
+import AgentProcess from "../agent-process.js";
+import {
+  buildFeatureLeadInitPrompt,
+  buildFeatureLeadRefreshPrompt,
+  buildFeatureLeadTriggerPrompt,
+} from "../prompt-builder.js";
+import {
+  IMPL_BASE, IRIAI_TEAM_DIR,
+  MAX_FL_RETRIES, MAX_FL_INIT_RETRIES,
+  FAST_EXIT_THRESHOLD_MS, FAST_EXIT_BACKOFF_S, FL_NORMAL_BACKOFF_S,
+  FL_CONTEXT_EXHAUST_MS,
+  SIGNAL, DASHBOARD_LOG, FEATURE_REVIEW_ROLES,
+} from "../constants.js";
+
+export default class FeatureLead extends EventEmitter {
+  /**
+   * @param {object} opts
+   * @param {string} opts.slug - Feature slug
+   * @param {string} opts.featureLeadDir - Feature Lead signal directory
+   * @param {string} opts.featureReviewDir - Feature review signal directory
+   * @param {string} opts.teamSignalBase - Teams signal base
+   * @param {number} opts.numTeams - Number of teams
+   * @param {string} opts.teamType - Team type (e.g., "dynamic")
+   * @param {string} [opts.model] - Claude model
+   * @param {object} [opts.featureState] - Live feature state ref (for gate_evidence_ts dedup)
+   */
+  constructor({ slug, featureLeadDir, featureReviewDir, teamSignalBase, numTeams, teamType, model, featureState }) {
+    super();
+    this.slug = slug;
+    this.featureLeadDir = featureLeadDir;
+    this.featureReviewDir = featureReviewDir;
+    this.teamSignalBase = teamSignalBase;
+    this.numTeams = numTeams;
+    this.teamType = teamType || "dynamic";
+    this.model = model || "opus";
+    this.key = `fl-${slug}`;
+    this._featureState = featureState || null;
+
+    this._agent = null;
+    this._state = "idle";
+    this._mainCrashCount = 0;
+    this._retryTimer = null;
+    this._dashboardTimer = null;
+    this._planReadInstruction = "";
+
+    this._resolvePlanPaths();
+  }
+
+  get state() { return this._state; }
+
+  /**
+   * Start the initial dispatch phase.
+   */
+  startInit() {
+    this._state = "dispatching";
+
+    // Check if this is a resume (gate > 0 in FEATURE-STATUS.md)
+    const featureStatus = path.join(IRIAI_TEAM_DIR, "FEATURE-STATUS.md");
+    let skipInit = false;
+    try {
+      const content = fs.readFileSync(featureStatus, "utf-8");
+      const gateMatch = content.match(/Current Gate[:\s]*(\d+)/i);
+      if (gateMatch && parseInt(gateMatch[1]) > 0) {
+        skipInit = true;
+      }
+    } catch { /* ok */ }
+
+    if (skipInit) {
+      // Resume in progress — spawn a refresh session to pick up where we left off
+      // (dispatch next gate, continue monitoring, etc.)
+      this.emit("lifecycle", { key: this.key, event: "resumed" });
+      this._spawnRefresh();
+      return;
+    }
+
+    this._spawnInit();
+  }
+
+  /**
+   * Handle a trigger detected by the bridge or signal watcher.
+   * Called when gate-ready, question, crash, or idle-redispatch detected externally.
+   */
+  handleTrigger(trigger, { questionTeams, crashedTeams } = {}) {
+    if (this._agent) {
+      // Kill current session before spawning trigger handler
+      this._agent.kill();
+      this._agent = null;
+    }
+
+    this._state = "handling-trigger";
+    this._spawnTrigger(trigger, { questionTeams, crashedTeams });
+  }
+
+  kill() {
+    if (this._agent) {
+      this._agent.kill();
+      this._agent = null;
+    }
+    if (this._dashboardTimer) {
+      clearInterval(this._dashboardTimer);
+      this._dashboardTimer = null;
+    }
+    this._state = "idle";
+  }
+
+  /**
+   * Handle .needs-restart signal for the Feature Lead (context handover).
+   * Reads .handover from disk and immediately calls _spawnRefresh() with that content.
+   */
+  handleNeedsRestart() {
+    const handoverPath = path.join(this.featureLeadDir, SIGNAL.HANDOVER);
+    let handoverContent = null;
+    try {
+      if (fs.existsSync(handoverPath)) {
+        handoverContent = fs.readFileSync(handoverPath, "utf8").trim();
+        fs.unlinkSync(handoverPath);
+      }
+    } catch { /* ignore */ }
+
+    const restartPath = path.join(this.featureLeadDir, SIGNAL.NEEDS_RESTART);
+    try { fs.unlinkSync(restartPath); } catch { /* ignore */ }
+
+    // Cancel any pending crash-retry timer to prevent double-spawn
+    if (this._retryTimer) {
+      clearTimeout(this._retryTimer);
+      this._retryTimer = null;
+    }
+
+    if (this._agent) {
+      this._agent.kill();
+      this._agent = null;
+    }
+
+    this._mainCrashCount = 0;
+    this.emit("lifecycle", { key: this.key, event: "handover-restart" });
+    this._spawnRefresh(handoverContent);
+  }
+
+  // ─── Init Phase ──────────────────────────────────────────────────────────
+
+  _spawnInit() {
+    // Clean signals
+    for (const sig of [SIGNAL.CONTEXT_REFRESH, SIGNAL.PHASE_DONE]) {
+      try { fs.unlinkSync(path.join(this.featureLeadDir, sig)); } catch { /* ok */ }
+    }
+
+    const prompt = buildFeatureLeadInitPrompt({
+      featureName: this.slug,
+      numTeams: this.numTeams,
+      teamType: this.teamType,
+      teamSignalBase: this.teamSignalBase,
+      planReadInstruction: this._planReadInstruction,
+      featureLeadDir: this.featureLeadDir,
+      featureReviewDir: this.featureReviewDir,
+      dashboardLog: DASHBOARD_LOG,
+    });
+
+    this._spawnSession(prompt, {
+      onPhaseDone: () => {
+        this._state = "monitoring";
+        this.emit("lifecycle", { key: this.key, event: "init-complete" });
+        this._startTriggerDetection();
+      },
+      onFeatureComplete: () => {
+        this._state = "complete";
+        this.emit("featureComplete", { key: this.key, slug: this.slug });
+        this.emit("lifecycle", { key: this.key, event: "feature-complete" });
+      },
+      onContextRefresh: () => {
+        this.emit("lifecycle", { key: this.key, event: "context-refresh" });
+        this._spawnRefresh();
+      },
+      onCrash: (elapsed) => this._handleCrash(elapsed, () => this._spawnInit()),
+      maxRetries: MAX_FL_INIT_RETRIES,
+    });
+
+    this.emit("lifecycle", { key: this.key, event: "init-started" });
+  }
+
+  // ─── Trigger Phase ───────────────────────────────────────────────────────
+
+  _spawnTrigger(trigger, { questionTeams, crashedTeams, recoveryContext } = {}) {
+    // Clean signals
+    for (const sig of [SIGNAL.PHASE_DONE, SIGNAL.CONTEXT_REFRESH]) {
+      try { fs.unlinkSync(path.join(this.featureLeadDir, sig)); } catch { /* ok */ }
+    }
+
+    const prompt = buildFeatureLeadTriggerPrompt({
+      featureName: this.slug,
+      numTeams: this.numTeams,
+      trigger,
+      teamSignalBase: this.teamSignalBase,
+      featureLeadDir: this.featureLeadDir,
+      featureReviewDir: this.featureReviewDir,
+      dashboardLog: DASHBOARD_LOG,
+      questionTeams: questionTeams || [],
+      crashedTeams: crashedTeams || [],
+      recoveryContext,
+    });
+
+    this._spawnSession(prompt, {
+      onPhaseDone: () => {
+        this._mainCrashCount = 0; // Reset on success
+        this.emit("lifecycle", { key: this.key, event: "phase-complete", trigger });
+        // After a gate review is approved, spawn a fresh session to dispatch the
+        // next gate. The prompt says "a new session will handle the next gate
+        // dispatch" — this is where that promise is fulfilled.
+        if (trigger === "gate-ready") {
+          this._spawnRefresh();
+        } else {
+          this._state = "monitoring";
+          this._startTriggerDetection();
+        }
+      },
+      onFeatureComplete: () => {
+        this._state = "complete";
+        this.emit("featureComplete", { key: this.key, slug: this.slug });
+        this.emit("lifecycle", { key: this.key, event: "feature-complete" });
+      },
+      onContextRefresh: () => {
+        this.emit("lifecycle", { key: this.key, event: "context-refresh" });
+        this._spawnRefresh();
+      },
+      onCrash: (elapsed) => this._handleCrash(elapsed, () => {
+        this._spawnTrigger(trigger, { questionTeams, crashedTeams, recoveryContext: true });
+      }),
+      maxRetries: MAX_FL_RETRIES,
+    });
+
+    this.emit("lifecycle", { key: this.key, event: "trigger-started", trigger });
+  }
+
+  // ─── Refresh/Continue ────────────────────────────────────────────────────
+
+  _spawnRefresh(handoverContent = null) {
+    // Clean stale signals before spawning (matches _spawnInit and _spawnTrigger)
+    for (const sig of [SIGNAL.CONTEXT_REFRESH, SIGNAL.PHASE_DONE]) {
+      try { fs.unlinkSync(path.join(this.featureLeadDir, sig)); } catch { /* ok */ }
+    }
+
+    const gateEvidenceTs = this._featureState?.gate_evidence_ts || null;
+    const prompt = buildFeatureLeadRefreshPrompt({
+      featureName: this.slug,
+      numTeams: this.numTeams,
+      teamSignalBase: this.teamSignalBase,
+      planReadInstruction: this._planReadInstruction,
+      featureLeadDir: this.featureLeadDir,
+      featureReviewDir: this.featureReviewDir,
+      dashboardLog: DASHBOARD_LOG,
+      gateEvidenceTs,
+    });
+
+    const fullPrompt = handoverContent
+      ? `HANDOVER CONTEXT FROM PREVIOUS SESSION:\n${handoverContent}\n\n---\n\n${prompt}`
+      : prompt;
+
+    this._spawnSession(fullPrompt, {
+      onPhaseDone: () => {
+        this._mainCrashCount = 0;
+        this.emit("lifecycle", { key: this.key, event: "refresh-complete" });
+        // Chain to a fresh session to dispatch the next gate — same as
+        // _spawnTrigger("gate-ready") does. Without this, the FL drops
+        // into monitoring with no process and no trigger detection,
+        // causing the next gate to never be dispatched.
+        this._spawnRefresh();
+      },
+      onFeatureComplete: () => {
+        this._state = "complete";
+        this.emit("featureComplete", { key: this.key, slug: this.slug });
+      },
+      onContextRefresh: () => {
+        this._spawnRefresh(); // Recursive refresh
+      },
+      onCrash: (elapsed) => this._handleCrash(elapsed, () => this._spawnRefresh()),
+      maxRetries: MAX_FL_RETRIES,
+    });
+  }
+
+  // ─── Shared Session Spawning ─────────────────────────────────────────────
+
+  _spawnSession(prompt, { onPhaseDone, onFeatureComplete, onContextRefresh, onCrash, maxRetries }) {
+    this._agent = new AgentProcess({
+      key: this.key,
+      cwd: IRIAI_TEAM_DIR,
+      extraEnv: { IMPL_SIGNAL_BASE: IMPL_BASE },
+      signalDir: this.featureLeadDir,
+    });
+    this._agent.spawnClaude(prompt, { model: this.model });
+
+    this._agent.on("exit", ({ elapsed }) => {
+      this._agent = null;
+
+      // Check for .feature-complete FIRST
+      if (fs.existsSync(path.join(this.featureLeadDir, SIGNAL.FEATURE_COMPLETE))) {
+        onFeatureComplete();
+        return;
+      }
+
+      // Check for .context-refresh
+      if (fs.existsSync(path.join(this.featureLeadDir, SIGNAL.CONTEXT_REFRESH))) {
+        try { fs.unlinkSync(path.join(this.featureLeadDir, SIGNAL.CONTEXT_REFRESH)); } catch { /* ok */ }
+        onContextRefresh();
+        return;
+      }
+
+      // Check for .phase-done
+      if (fs.existsSync(path.join(this.featureLeadDir, SIGNAL.PHASE_DONE))) {
+        try { fs.unlinkSync(path.join(this.featureLeadDir, SIGNAL.PHASE_DONE)); } catch { /* ok */ }
+        onPhaseDone();
+        return;
+      }
+
+      // Check for .needs-restart — signal watcher will call handleNeedsRestart()
+      // Don't count as crash; the watcher handles the respawn.
+      if (fs.existsSync(path.join(this.featureLeadDir, SIGNAL.NEEDS_RESTART))) {
+        this.emit("lifecycle", { key: this.key, event: "needs-restart-exit" });
+        return;
+      }
+
+      // No signal — check for auto-refresh (ran > 5min = likely context exhaustion)
+      if (elapsed >= FL_CONTEXT_EXHAUST_MS) {
+        this.emit("lifecycle", { key: this.key, event: "auto-context-refresh" });
+        onContextRefresh();
+        return;
+      }
+
+      // Short-lived exit = real crash
+      onCrash(elapsed);
+    });
+  }
+
+  _handleCrash(elapsed, retryFn) {
+    this._mainCrashCount++;
+    const isFast = elapsed < FAST_EXIT_THRESHOLD_MS;
+    const backoffS = isFast
+      ? this._mainCrashCount * FAST_EXIT_BACKOFF_S
+      : this._mainCrashCount * FL_NORMAL_BACKOFF_S;
+
+    if (this._mainCrashCount >= MAX_FL_RETRIES) {
+      // Instead of pausing indefinitely, do a context-refresh restart
+      this._mainCrashCount = 0;
+      this.emit("lifecycle", { key: this.key, event: "auto-restart-after-crashes" });
+      this._spawnRefresh();
+      return;
+    }
+
+    this._state = "retrying";
+    this.emit("lifecycle", {
+      key: this.key,
+      event: "crash-retry",
+      retryCount: this._mainCrashCount,
+      backoffS,
+    });
+
+    this._retryTimer = setTimeout(() => {
+      this._retryTimer = null;
+      retryFn();
+    }, backoffS * 1000);
+  }
+
+  // ─── Trigger Detection ───────────────────────────────────────────────────
+
+  _startTriggerDetection() {
+    // In v2 bridge, trigger detection is event-driven via SignalWatcher.
+    // The bridge wires signal events to handleTrigger(). This method is a
+    // no-op; kept for documentation.
+  }
+
+  // ─── Plan Paths ──────────────────────────────────────────────────────────
+
+  _resolvePlanPaths() {
+    const defaultPath = path.join(IRIAI_TEAM_DIR, "implementation-plans", "current/");
+    const proposalFile = path.join(IRIAI_TEAM_DIR, ".feature-proposal");
+
+    try {
+      if (fs.existsSync(proposalFile)) {
+        const content = fs.readFileSync(proposalFile, "utf-8");
+        const pathsMatch = content.match(/^plan_paths:\s*(.+)$/m);
+        const sourceMatch = content.match(/^plan_source:\s*(.+)$/m);
+        if (pathsMatch) {
+          const savedPaths = pathsMatch[1].trim();
+          const source = sourceMatch ? sourceMatch[1].trim() : "dir";
+          const firstPath = savedPaths.split(/\s+/)[0];
+          if (fs.existsSync(firstPath)) {
+            if (source === "files") {
+              this._planReadInstruction = `Read the following implementation plan file(s) in order:\n${
+                savedPaths.split(/\s+/).map((p) => `- ${p}`).join("\n")
+              }`;
+            } else {
+              this._planReadInstruction = `Read the implementation plan at ${savedPaths}.`;
+            }
+            return;
+          }
+        }
+      }
+    } catch { /* ok */ }
+
+    this._planReadInstruction = `Read the implementation plan at ${defaultPath}.`;
+  }
+}

package/lib/state-machines/operator-agent.js

@@ -0,0 +1,173 @@
+// operator-agent.js — Per-message operator agent.
+// Replaces run-operator.sh. No retries — one fresh claude session per message.
+//
+// State: IDLE ──[signal:userMessage]──→ RUNNING ──[process:exit]──→ IDLE
+
+import { EventEmitter } from "node:events";
+import fs from "node:fs";
+import path from "node:path";
+import AgentProcess from "../agent-process.js";
+import { buildOperatorPrompt } from "../prompt-builder.js";
+import { IMPL_BASE, IRIAI_TEAM_DIR, SIGNAL } from "../constants.js";
+
+const POLL_INTERVAL_MS = 30_000; // Safety net: check for abandoned .user-message every 30s
+
+export default class OperatorAgent extends EventEmitter {
+  /**
+   * @param {object} opts
+   * @param {string} opts.slug - Feature slug
+   * @param {string} opts.operatorDir - Operator signal directory
+   * @param {string} opts.flDir - Feature Lead signal directory
+   * @param {string} opts.featureDir - Feature signal tree root
+   */
+  constructor({ slug, operatorDir, flDir, featureDir }) {
+    super();
+    this.slug = slug;
+    this.operatorDir = operatorDir;
+    this.flDir = flDir;
+    this.featureDir = featureDir;
+    this.key = `op-${slug}`;
+    this._agent = null;
+    this._state = "idle";
+    this.historyFile = path.join(operatorDir, SIGNAL.CONVERSATION_HISTORY);
+    this._pollTimer = null;
+    this._startPoll();
+  }
+
+  get state() { return this._state; }
+
+  /**
+   * Handle an incoming user message (triggered by SignalWatcher).
+   */
+  handleUserMessage() {
+    if (this._state === "running") {
+      console.log(`[operator] ${this.key}: already running, ignoring message`);
+      return;
+    }
+
+    const msgPath = path.join(this.operatorDir, SIGNAL.USER_MESSAGE);
+    let userMsg;
+    try {
+      userMsg = fs.readFileSync(msgPath, "utf-8").trim();
+      fs.unlinkSync(msgPath);
+    } catch {
+      return;
+    }
+    if (!userMsg) return;
+
+    this._state = "running";
+    this._appendHistory("user", userMsg);
+    const history = this._getHistory();
+
+    let prompt;
+    try {
+      prompt = buildOperatorPrompt({
+        featureName: this.slug,
+        operatorDir: this.operatorDir,
+        flDir: this.flDir,
+        featureDir: this.featureDir,
+        history,
+        userMessage: userMsg,
+      });
+    } catch (err) {
+      console.error(`[operator] ${this.key}: prompt build failed:`, err.message);
+      this._state = "idle";
+      return;
+    }
+
+    try {
+      this._agent = new AgentProcess({
+        key: this.key,
+        cwd: this.operatorDir,
+        extraEnv: { IMPL_SIGNAL_BASE: IMPL_BASE },
+        signalDir: this.operatorDir,
+      });
+
+      this._agent.spawnClaude(prompt, { model: "opus" });
+    } catch (err) {
+      console.error(`[operator] ${this.key}: spawn failed:`, err.message);
+      this._agent = null;
+      this._state = "idle";
+      return;
+    }
+
+    this._agent.on("exit", ({ exitCode }) => {
+      // Check for .agent-response
+      const responsePath = path.join(this.operatorDir, SIGNAL.AGENT_RESPONSE);
+      if (fs.existsSync(responsePath)) {
+        const response = fs.readFileSync(responsePath, "utf-8").trim();
+        this._appendHistory("operator", response);
+      } else if (exitCode !== 0) {
+        // Agent crashed — write fallback response
+        fs.writeFileSync(
+          responsePath,
+          "Something went wrong processing your message. Please try again."
+        );
+        this._appendHistory("operator", "(failed to respond)");
+      }
+
+      this._agent = null;
+      this._state = "idle";
+      this.emit("idle", { key: this.key });
+
+      // Drain on next tick to avoid spawning PTY inside PTY exit callback
+      setImmediate(() => this._drainPending());
+    });
+
+    this.emit("running", { key: this.key });
+  }
+
+  kill() {
+    if (this._agent) {
+      this._agent.kill();
+      this._agent = null;
+    }
+    this._state = "idle";
+    if (this._pollTimer) {
+      clearInterval(this._pollTimer);
+      this._pollTimer = null;
+    }
+  }
+
+  /** Safety net: periodically check for abandoned .user-message when idle */
+  _startPoll() {
+    this._pollTimer = setInterval(() => {
+      this._drainPending();
+    }, POLL_INTERVAL_MS);
+  }
+
+  _drainPending() {
+    if (this._state !== "idle") return;
+    const pendingMsg = path.join(this.operatorDir, SIGNAL.USER_MESSAGE);
+    try {
+      if (fs.existsSync(pendingMsg)) {
+        console.log(`[operator] ${this.key}: draining pending .user-message`);
+        this.handleUserMessage();
+      }
+    } catch (err) {
+      console.error(`[operator] ${this.key}: drain error:`, err.message);
+      this._state = "idle";
+    }
+  }
+
+  _appendHistory(role, content) {
+    const ts = new Date().toTimeString().slice(0, 8);
+    fs.appendFileSync(this.historyFile, `[${ts}] ${role}: ${content}\n`);
+
+    // Rotate at 200 lines
+    try {
+      const lines = fs.readFileSync(this.historyFile, "utf-8").split("\n");
+      if (lines.length > 200) {
+        fs.writeFileSync(this.historyFile, lines.slice(-100).join("\n"));
+      }
+    } catch { /* ignore */ }
+  }
+
+  _getHistory() {
+    try {
+      return fs.readFileSync(this.historyFile, "utf-8");
+    } catch {
+      return "(no prior conversation)";
+    }
+  }
+}