iriai-build 0.5.2 → 0.6.0

package/bridge-v3.js

@@ -47,7 +47,7 @@ async function start() {
   console.log(`Slack connected. Bot user: ${adapter.botUserId}`);
 
   // 3. Create orchestrator with review session support
-  const reviewSessions = new ReviewSessionManager();
+  const reviewSessions = new ReviewSessionManager({ portalPort: PORTAL_PORT });
   const orchestrator = new Orchestrator({ adapter, reviewSessions });
   _orchestrator = orchestrator;
   adapter.setOrchestrator(orchestrator);

package/cli/bootstrap.js

@@ -24,7 +24,7 @@ export function bootstrap({ budgetOverride } = {}) {
 
   const budget = resolveBudget(budgetOverride);
   const adapter = new TerminalAdapter();
-  const reviewSessions = new ReviewSessionManager();
+  const reviewSessions = new ReviewSessionManager({ portalPort: PORTAL_PORT });
   const orchestrator = new Orchestrator({ adapter, reviewSessions, budget });
   const input = new TerminalInput({ orchestrator });
   adapter.setInputHandler(input);

package/cli/commands/slack.js

@@ -41,7 +41,7 @@ export async function slackCommand() {
   await adapter.connect();
   console.log(`Slack connected. Bot user: ${adapter.botUserId}`);
 
-  const reviewSessions = new ReviewSessionManager();
+  const reviewSessions = new ReviewSessionManager({ portalPort: PORTAL_PORT });
   const orchestrator = new Orchestrator({ adapter, reviewSessions });
   adapter.setOrchestrator(orchestrator);
 

package/cli/commands/transfer.js

@@ -8,7 +8,7 @@ import { Orchestrator } from "../../v3/orchestrator.js";
 import { Recovery } from "../../v3/recovery.js";
 import { ReviewSessionManager } from "../../v3/review-sessions.js";
 import * as queries from "../../v3/queries.js";
-import { DB_PATH } from "../../v3/constants.js";
+import { DB_PATH, PORTAL_PORT } from "../../v3/constants.js";
 import * as config from "../config.js";
 import { banner, systemMsg, successMsg, errorMsg } from "../display.js";
 
@@ -50,7 +50,7 @@ export async function transferToSlackCommand() {
   successMsg(`Slack connected. Bot user: ${adapter.botUserId}`);
 
   // Create orchestrator
-  const reviewSessions = new ReviewSessionManager();
+  const reviewSessions = new ReviewSessionManager({ portalPort: PORTAL_PORT });
   const orchestrator = new Orchestrator({ adapter, reviewSessions });
   adapter.setOrchestrator(orchestrator);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iriai-build",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Iriai Build tool — AI agent orchestration CLI",
   "type": "module",
   "bin": {

package/v3/adapters/slack-adapter.js

@@ -147,7 +147,8 @@ export class SlackAdapter extends InterfaceAdapter {
   async uploadArtifact(featureId, filePath, title) {
     const channel = this._resolveChannel(featureId);
     const feature = queries.getFeatureById(featureId);
-    const threadTs = feature?.thread_ts || null;
+    // Only thread uploads in the planning channel — feature channels don't have this thread
+    const threadTs = (channel === this.planningChannel) ? (feature?.thread_ts || null) : null;
     await slackUploadArtifact(this.web, channel, threadTs, filePath, title);
   }
 
@@ -216,10 +217,11 @@ export class SlackAdapter extends InterfaceAdapter {
     const designPath = findArtifact("design-decisions", planDir);
     const planPath = findArtifact("implementation-plan", planDir);
 
-    // Upload artifacts FIRST
-    if (prdPath) await slackUploadArtifact(this.web, channel, feature.thread_ts, prdPath, "PRD");
-    if (designPath) await slackUploadArtifact(this.web, channel, feature.thread_ts, designPath, "Design Decisions");
-    if (planPath) await slackUploadArtifact(this.web, channel, feature.thread_ts, planPath, "Implementation Plan");
+    // Upload artifacts FIRST — no thread_ts in feature channels (thread belongs to planning channel)
+    const artThreadTs = (channel === this.planningChannel) ? feature.thread_ts : null;
+    if (prdPath) await slackUploadArtifact(this.web, channel, artThreadTs, prdPath, "PRD");
+    if (designPath) await slackUploadArtifact(this.web, channel, artThreadTs, designPath, "Design Decisions");
+    if (planPath) await slackUploadArtifact(this.web, channel, artThreadTs, planPath, "Implementation Plan");
 
     // Post approval with Block Kit buttons AFTER uploads
     const blocks = buildDecisionBlocks(

package/v3/artifact-portal.js

@@ -2,7 +2,7 @@
 // Serves on a single port (default 8900) with feature index, tabbed detail, and individual artifact views.
 // Reuses plan-compiler.js CSS/rendering patterns (Charter fonts, frosted glass, marked.js + mermaid.js).
 
-import { createServer } from "node:http";
+import { createServer, request as httpRequest } from "node:http";
 import fs from "node:fs";
 import path from "node:path";
 import { IMPL_BASE } from "./constants.js";
@@ -61,6 +61,12 @@ export class ArtifactPortal {
         return this._serveArtifact(res, artifactMatch[1], artifactMatch[2]);
       }
 
+      // Review session proxy: /review/<decisionId>/... → internal iriai-feedback port
+      const reviewMatch = pathname.match(/^\/review\/([^/]+)(\/.*)?$/);
+      if (reviewMatch) {
+        return this._proxyReviewSession(req, res, decodeURIComponent(reviewMatch[1]), reviewMatch[2] || "/");
+      }
+
       res.writeHead(404, { "Content-Type": "text/html" });
       res.end(this._render404());
     } catch (err) {
@@ -158,6 +164,51 @@ export class ArtifactPortal {
     res.end(content);
   }
 
+  // ─── Review Session Proxy ─────────────────────────────────────────
+
+  /**
+   * Reverse proxy requests from /review/<decisionId>/... to the internal
+   * iriai-feedback port for that session. Supports multiple concurrent
+   * review sessions (e.g., parallel gate reviews for different teams).
+   */
+  _proxyReviewSession(clientReq, clientRes, decisionId, subpath) {
+    if (!this._reviewSessions) {
+      clientRes.writeHead(502, { "Content-Type": "text/plain" });
+      clientRes.end("Review sessions not available");
+      return;
+    }
+
+    const port = this._reviewSessions.getSessionPort(decisionId);
+    if (!port) {
+      clientRes.writeHead(404, { "Content-Type": "text/plain" });
+      clientRes.end(`No active review session for: ${decisionId}`);
+      return;
+    }
+
+    const proxyOpts = {
+      hostname: "127.0.0.1",
+      port,
+      path: subpath,
+      method: clientReq.method,
+      headers: { ...clientReq.headers, host: `localhost:${port}` },
+    };
+
+    const proxyReq = httpRequest(proxyOpts, (proxyRes) => {
+      clientRes.writeHead(proxyRes.statusCode, proxyRes.headers);
+      proxyRes.pipe(clientRes, { end: true });
+    });
+
+    proxyReq.on("error", (err) => {
+      console.error(`[artifact-portal] Review proxy error (${decisionId}):`, err.message);
+      if (!clientRes.headersSent) {
+        clientRes.writeHead(502, { "Content-Type": "text/plain" });
+        clientRes.end("Review session unavailable");
+      }
+    });
+
+    clientReq.pipe(proxyReq, { end: true });
+  }
+
   // ─── Data Helpers ──────────────────────────────────────────────────
 
   _getAllFeaturesWithArtifacts() {

package/v3/orchestrator.js

@@ -1653,6 +1653,97 @@ export class Orchestrator {
     queries.insertEvent(featureId, "gate-rejected", "bridge", `Gate rejected (teams ${reviewTeams.join(", ")}): ${reason}`);
   }
 
+  /**
+   * Handle a gate [DECISION] block from the Feature Lead's .agent-response.
+   * Mirrors the planning deferred-decision pattern: start doc-review, create
+   * the decision as deferred, relay through operator as "decision-needed",
+   * and ack the FL to stop re-posting.
+   */
+  async _handleGateDecisionFromFL(feature, gateDecision, plainText) {
+    const tree = this._signalTrees[feature.slug];
+
+    const options = gateDecision.options.map(o => ({
+      id: o.id,
+      label: o.label,
+      style: o.style || "default",
+      description: o.description || "",
+    }));
+
+    // Start doc-review session for gate evidence HTML (same as inline gate code in impl:operatorResponse)
+    let reviewUrl = null;
+    let qaUrl = null;
+    const reviewSessionKey = `${gateDecision.id}@${feature.slug}`;
+
+    if (this.reviewSessions) {
+      const evidencePath = path.join(feature.signal_dir, "feature-lead", ".gate-evidence.html");
+      if (fs.existsSync(evidencePath)) {
+        reviewUrl = await this.reviewSessions.startDocReview(
+          reviewSessionKey, evidencePath, `Gate Evidence — ${gateDecision.title}`, { featureId: feature.id }
+        );
+      }
+
+      // Start QA session if verification config specifies local-server
+      const verification = this._readVerificationConfig(feature);
+      if (verification && verification.type === "local-server" && verification.url) {
+        let devServerOk = !verification.command;
+        if (verification.command) {
+          try {
+            const featureReposDir = path.join(PROJECT_ROOT, ".features", feature.slug, "repos");
+            await new Promise((resolve) => {
+              const proc = cpSpawn("sh", ["-c", verification.command], {
+                cwd: featureReposDir,
+                stdio: "ignore",
+                detached: true,
+              });
+              proc.on("error", (err) => {
+                console.error(`[orchestrator] Dev server spawn error: ${err.message}`);
+                resolve(false);
+              });
+              proc.unref();
+              setTimeout(() => resolve(true), 3000);
+            }).then(ok => { devServerOk = ok; });
+          } catch (err) {
+            console.error(`[orchestrator] Failed to start dev server for gate review:`, err.message);
+          }
+        }
+        if (devServerOk) {
+          qaUrl = await this.reviewSessions.startQaSession(
+            reviewSessionKey, verification.url, { featureId: feature.id }
+          );
+        }
+      }
+    }
+
+    const decision = {
+      id: gateDecision.id,
+      title: gateDecision.title,
+      context: gateDecision.context,
+      type: gateDecision.type || "approval",
+      options,
+      reviewUrl,
+      qaUrl,
+    };
+
+    // Defer the decision post until after the Operator relay completes
+    this._deferredDecisions[feature.id] = { decision, featureId: feature.id };
+
+    // Notify the Operator via relay (eventHint: "decision-needed" ensures
+    // fallback skips raw text and just posts the deferred decision)
+    this._notifyOperatorOfDecision(feature, decision, plainText);
+
+    // Ack the FL so it stops polling / re-posting gate evidence
+    if (tree?.featureLead) {
+      writeSignal(path.join(tree.featureLead, SIGNAL.USER_MESSAGE),
+        `Gate evidence received and posted for user review. Waiting for user decision — do NOT re-post.`);
+    }
+
+    // Pre-set gate_evidence_ts with a placeholder so FL refresh prompts know
+    // evidence was already posted (actual Slack ts is set after deferred post)
+    queries.updateFeatureGateEvidenceTs(feature.id, "pending");
+
+    console.log(`[orchestrator] Gate decision ${gateDecision.id} intercepted from FL, deferred for operator relay`);
+  }
+
   // ─── Gate Team Dependency Resolution ─────────────────────────────────
 
   /**
@@ -2272,6 +2363,16 @@ export class Orchestrator {
         if (!content) return;
         const feature = queries.getFeatureBySlug(slug);
         if (!feature) return;
+
+        // Intercept gate decisions: use deferred decision pattern (same as planning)
+        // so the gate review gets doc-review + properly formatted Block Kit buttons
+        const parsed = parseOperatorResponse(content);
+        const gateDecision = parsed.decisions.find(d => d.id && d.id.startsWith("gate-"));
+        if (gateDecision) {
+          await this._handleGateDecisionFromFL(feature, gateDecision, parsed.plainText);
+          return;
+        }
+
         await this._enqueueForOperatorRelay(feature, "Feature Lead", "fl-response", content);
       } catch (err) {
         console.error("[orchestrator] Impl response error:", err.message);
@@ -3405,16 +3506,40 @@ modify a SPECIFIC section — never re-read them in full.\n`;
   }
 
   /**
-   * Post a deferred decision (stored by _requestPhaseReview) after the Operator
-   * relay completes, so the decision buttons appear after the Operator's message.
+   * Post a deferred decision (stored by _requestPhaseReview or _handleGateDecisionFromFL)
+   * 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];
 
+    const { decision } = deferred;
+
     try {
-      await this.adapter.postDecision(deferred.featureId, deferred.decision);
+      const decResult = await this.adapter.postDecision(deferred.featureId, decision);
+
+      // For gate decisions: store in DB and update gate_evidence_ts with actual ref
+      if (decision.type === "approval" && decision.id.startsWith("gate-")) {
+        queries.createDecision({
+          featureId: deferred.featureId,
+          decisionId: decision.id,
+          decisionType: decision.type || "approval",
+          title: decision.title,
+          contextText: decision.context || null,
+          options: decision.options,
+        });
+
+        const feature = queries.getFeatureById(deferred.featureId);
+        const decChannel = feature?.feature_channel || this.adapter.planningChannel;
+        queries.updateDecisionSlack(deferred.featureId, decision.id, {
+          slackTs: decResult?.ref || null,
+          slackChannel: decChannel || null,
+          permalink: null,
+        });
+
+        queries.updateFeatureGateEvidenceTs(deferred.featureId, decResult?.ref || null);
+      }
     } catch (err) {
       console.error("[orchestrator] Failed to post deferred decision:", err.message);
     }

package/v3/review-sessions.js

@@ -1,11 +1,16 @@
 // review-sessions.js — Manages interactive review tool sessions for decisions.
 // Loosely coupled: uses iriai-feedback CLI (child_process.spawn) + HTTP API.
 // No direct imports from iriai-feedback.
+//
+// Doc-review and QA sessions are proxied through the artifact portal so users
+// see stable URLs (http://localhost:<portalPort>/review/<decisionId>/...) instead
+// of ephemeral per-session ports.
 
 import { spawn } from "node:child_process";
 import { createServer } from "node:http";
 import { get as httpGet } from "node:http";
 import { readFile } from "node:fs/promises";
+import { createConnection } from "node:net";
 import * as queries from "./queries.js";
 import { get as configGet } from "../cli/config.js";
 
@@ -14,18 +19,55 @@ const PORT_MIN = 9001;
 const PORT_MAX = 9020;
 
 export class ReviewSessionManager {
-  constructor() {
+  constructor({ portalPort } = {}) {
     this._sessions = new Map(); // decisionId -> { sessionId, url, port, process, type, qa? }
     this._nextPort = PORT_MIN;
+    this._portalPort = portalPort || 8900;
   }
 
-  _allocPort() {
+  /**
+   * Probe whether a port is actually free by attempting a TCP connection.
+   * Returns true if nothing is listening (connection refused), false if occupied.
+   */
+  _isPortFree(port) {
+    return new Promise((resolve) => {
+      const conn = createConnection({ port, host: "127.0.0.1" });
+      conn.once("connect", () => {
+        conn.destroy();
+        resolve(false); // something is listening → port is occupied
+      });
+      conn.once("error", () => {
+        resolve(true); // connection refused → port is free
+      });
+      conn.setTimeout(500, () => {
+        conn.destroy();
+        resolve(true); // timeout → assume free
+      });
+    });
+  }
+
+  async _allocPort() {
     const usedPorts = new Set(
       [...this._sessions.values()].flatMap(s =>
         [s.port, s.qa?.port].filter(Boolean)
       )
     );
     let port = this._nextPort;
+    let attempts = 0;
+    const range = PORT_MAX - PORT_MIN + 1;
+
+    while (attempts < range) {
+      if (!usedPorts.has(port) && await this._isPortFree(port)) {
+        this._nextPort = port >= PORT_MAX ? PORT_MIN : port + 1;
+        return port;
+      }
+      port = port >= PORT_MAX ? PORT_MIN : port + 1;
+      attempts++;
+    }
+
+    // Fallback: return next non-map port (best effort)
+    console.warn("[review-sessions] No verified-free ports; falling back to map-only check");
+    port = this._nextPort;
     while (usedPorts.has(port)) {
       port = port >= PORT_MAX ? PORT_MIN : port + 1;
     }
@@ -33,19 +75,27 @@ export class ReviewSessionManager {
     return port;
   }
 
+  /**
+   * Build the user-facing URL for a review session.
+   * Routes through the artifact portal's reverse proxy.
+   */
+  _buildReviewUrl(decisionId, subpath = "/doc-review") {
+    return `http://localhost:${this._portalPort}/review/${encodeURIComponent(decisionId)}${subpath}`;
+  }
+
   /**
    * Start a doc review session for a decision.
    * Spawns `iriai-feedback review <docPath> --port <port>`.
-   * Returns the review URL.
+   * Returns the portal-proxied review URL.
    */
   async startDocReview(decisionId, docPath, title, { featureId, port: preferredPort } = {}) {
-    const port = preferredPort || this._allocPort();
+    const port = preferredPort || await this._allocPort();
     const args = ["review", docPath, "--port", String(port)];
     if (title) args.push("--title", title);
 
     try {
       const { proc, sessionId } = await this._spawnAndParse(args);
-      const url = `http://localhost:${port}/doc-review`;
+      const url = this._buildReviewUrl(decisionId);
       this._sessions.set(decisionId, { sessionId, url, port, process: proc, type: "doc", docPath });
 
       // Persist to SQLite for restart recovery
@@ -69,7 +119,7 @@ export class ReviewSessionManager {
    */
   async startMockupReview(decisionId, htmlPath, { featureId } = {}) {
     // 1. Spin up a tiny static file server for the HTML mockup
-    const staticPort = this._allocPort();
+    const staticPort = await this._allocPort();
     const staticServer = await this._startStaticServer(htmlPath, staticPort);
 
     // 2. Wrap it with QA proxy
@@ -128,12 +178,12 @@ export class ReviewSessionManager {
    * Attaches to an existing decision entry if one exists.
    */
   async startQaSession(decisionId, targetUrl, { featureId, port: preferredPort } = {}) {
-    const port = preferredPort || this._allocPort();
+    const port = preferredPort || await this._allocPort();
     const args = ["start", targetUrl, "--port", String(port)];
 
     try {
       const { proc, sessionId } = await this._spawnAndParse(args);
-      const qaUrl = `http://localhost:${port}`;
+      const qaUrl = this._buildReviewUrl(decisionId, "");
       const existing = this._sessions.get(decisionId);
 
       if (existing) {
@@ -156,6 +206,22 @@ export class ReviewSessionManager {
     }
   }
 
+  /**
+   * Get the internal port for a session (used by the artifact portal proxy).
+   */
+  getSessionPort(decisionId) {
+    const session = this._sessions.get(decisionId);
+    return session?.port || null;
+  }
+
+  /**
+   * Get the QA session port for a session (used by the artifact portal proxy).
+   */
+  getQaPort(decisionId) {
+    const session = this._sessions.get(decisionId);
+    return session?.qa?.port || null;
+  }
+
   /**
    * Collect annotations from all active review servers for a decision.
    * Returns array of annotations or null if none.
@@ -219,17 +285,15 @@ export class ReviewSessionManager {
       });
     }
 
-    // Re-spawn the doc review server with the same port and doc path
+    // Re-spawn the doc review server (don't reuse stored port — it may be stale)
     const url = await this.startDocReview(decisionId, row.doc_path, null, {
       featureId: row.feature_id,
-      port: row.port,
     });
 
     // Re-spawn QA session if one was active
-    if (row.qa_target_url && row.qa_port) {
+    if (row.qa_target_url) {
       await this.startQaSession(decisionId, row.qa_target_url, {
         featureId: row.feature_id,
-        port: row.qa_port,
       });
     }
 
@@ -243,6 +307,19 @@ export class ReviewSessionManager {
     return this._sessions.has(decisionId);
   }
 
+  /**
+   * Get all active sessions (for portal listing).
+   */
+  getAllSessions() {
+    return [...this._sessions.entries()].map(([id, s]) => ({
+      decisionId: id,
+      type: s.type,
+      port: s.port,
+      url: s.url,
+      docPath: s.docPath,
+    }));
+  }
+
   // ─── Internal helpers ────────────────────────────────────────────────
 
   /**
@@ -258,13 +335,20 @@ export class ReviewSessionManager {
       });
 
       let stdout = "";
+      let stderr = "";
       let resolved = false;
 
       const timer = setTimeout(() => {
         if (!resolved) {
           resolved = true;
-          // Even if we didn't parse a session ID, the server may be running
-          resolve({ proc, sessionId: `session-${Date.now()}` });
+          // Check stderr for bind errors before accepting
+          if (stderr.includes("EADDRINUSE") || stderr.includes("address already in use")) {
+            reject(new Error(`Port already in use: ${stderr.trim()}`));
+            try { proc.kill("SIGKILL"); } catch { /* ok */ }
+          } else {
+            // Even if we didn't parse a session ID, the server may be running
+            resolve({ proc, sessionId: `session-${Date.now()}` });
+          }
         }
       }, 5000);
 
@@ -282,6 +366,17 @@ export class ReviewSessionManager {
         }
       });
 
+      proc.stderr.on("data", (chunk) => {
+        stderr += chunk.toString();
+        // Detect bind errors immediately
+        if (!resolved && (stderr.includes("EADDRINUSE") || stderr.includes("address already in use"))) {
+          resolved = true;
+          clearTimeout(timer);
+          reject(new Error(`Port already in use: ${stderr.trim()}`));
+          try { proc.kill("SIGKILL"); } catch { /* ok */ }
+        }
+      });
+
       proc.on("error", (err) => {
         if (!resolved) {
           resolved = true;
@@ -324,7 +419,12 @@ export class ReviewSessionManager {
   _killProc(proc) {
     if (!proc) return;
     try {
-      proc.kill("SIGINT");
+      proc.kill("SIGTERM");
+      // Follow up with SIGKILL after grace period to ensure cleanup
+      const killTimer = setTimeout(() => {
+        try { proc.kill("SIGKILL"); } catch { /* already dead */ }
+      }, 2000);
+      killTimer.unref();
     } catch {
       // Process may already be dead
     }