triflux 10.20.0 → 10.20.2

package/hub/team/swarm-hypervisor.mjs

@@ -241,6 +241,7 @@ export function createSwarmHypervisor(opts) {
     integrationFailures: [],
     skipped: [],
     integrationBranch: null,
+    report: [],
     processCleanup: {
       totalKilled: 0,
       byCategory: {},
@@ -319,6 +320,9 @@ export function createSwarmHypervisor(opts) {
       ]),
       skipped: Object.freeze([...(payload.skipped || [])]),
       integrationBranch: payload.integrationBranch || null,
+      report: Object.freeze(
+        (payload.report || []).map((row) => Object.freeze({ ...row })),
+      ),
       results: Object.freeze([...(payload.results || [])]),
       processCleanup: Object.freeze({
         totalKilled: processCleanup.totalKilled || 0,
@@ -340,6 +344,7 @@ export function createSwarmHypervisor(opts) {
       integrationFailures: [...integrationResult.integrationFailures],
       skipped: [...integrationResult.skipped],
       integrationBranch: integrationResult.integrationBranch,
+      report: integrationResult.report.map((row) => ({ ...row })),
       processCleanup: integrationResult.processCleanup,
       error: integrationResult.error,
     };
@@ -373,6 +378,20 @@ export function createSwarmHypervisor(opts) {
     return getProcessCleanupSummary();
   }
 
+  function normalizeIntegrationReportRow(row) {
+    return {
+      shard: row.shard,
+      strategy: row.strategy || "failed",
+      commits:
+        Number.isFinite(Number(row.commits)) && row.commits !== null
+          ? Number(row.commits)
+          : null,
+      finalSha: row.finalSha || null,
+      notes: row.notes || "",
+      recoveryPatch: row.recoveryPatch || null,
+    };
+  }
+
   function git(args, cwd = workdir) {
     return new Promise((resolve, reject) => {
       execFile(
@@ -964,9 +983,23 @@ export function createSwarmHypervisor(opts) {
 
     const integrated = [];
     const integrationFailures = [];
+    const integrationReport = [];
     const preIntegrationFailures = [...failures.keys()];
     let integrationBranch = null;
 
+    const appendIntegrationReport = (row) => {
+      const normalized = normalizeIntegrationReportRow(row);
+      integrationReport.push(normalized);
+      eventLog.append("integration_shard_report", normalized);
+      return normalized;
+    };
+
+    const failureNotes = (shardName, fallback = "failed") => {
+      const info = failures.get(shardName);
+      if (!info) return fallback;
+      return info.reason || info.mode || fallback;
+    };
+
     try {
       ({ integrationBranch } = await prepareIntegrationBranchImpl({
         runId,
@@ -977,6 +1010,11 @@ export function createSwarmHypervisor(opts) {
       for (const shardName of plan.mergeOrder) {
         if (failures.has(shardName)) {
           eventLog.append("skip_failed_shard", { shard: shardName });
+          appendIntegrationReport({
+            shard: shardName,
+            strategy: "failed",
+            notes: `skipped: ${failureNotes(shardName)}`,
+          });
           continue;
         }
 
@@ -1002,11 +1040,22 @@ export function createSwarmHypervisor(opts) {
               shard: shardName,
               error: fetchResult.error,
             });
-            await maybeCleanupWorktree(shardName, worker, shard, {
-              force: true,
-              failureReason: "remote_fetch_failed",
-            });
+            const cleanup = await maybeCleanupWorktree(
+              shardName,
+              worker,
+              shard,
+              {
+                force: true,
+                failureReason: "remote_fetch_failed",
+              },
+            );
             integrationFailures.push(shardName);
+            appendIntegrationReport({
+              shard: shardName,
+              strategy: "failed",
+              notes: `remote_fetch_failed: ${fetchResult.error || "unknown"}`,
+              recoveryPatch: cleanup?.recoveryPatch?.patchPath || null,
+            });
             continue;
           }
           eventLog.append("remote_fetch_ok", {
@@ -1042,12 +1091,20 @@ export function createSwarmHypervisor(opts) {
             shard: shardName,
             ...commitEvidence,
           });
-          await maybeCleanupWorktree(shardName, worker, shard, {
+          const cleanup = await maybeCleanupWorktree(shardName, worker, shard, {
             force: true,
             failureReason:
               failures.get(shardName)?.mode || "no_commit_evidence",
           });
           integrationFailures.push(shardName);
+          appendIntegrationReport({
+            shard: shardName,
+            strategy: "failed",
+            commits: commitEvidence.commitsAhead,
+            finalSha: commitEvidence.headCommit,
+            notes: failureNotes(shardName, "no_commit_evidence"),
+            recoveryPatch: cleanup?.recoveryPatch?.patchPath || null,
+          });
           continue;
         }
 
@@ -1065,12 +1122,18 @@ export function createSwarmHypervisor(opts) {
             shard: shardName,
             violations: validation.violations,
           });
-          await maybeCleanupWorktree(shardName, worker, shard, {
+          const cleanup = await maybeCleanupWorktree(shardName, worker, shard, {
             force: true,
             failureReason:
               failures.get(shardName)?.mode || "lease_violation_revert",
           });
           integrationFailures.push(shardName);
+          appendIntegrationReport({
+            shard: shardName,
+            strategy: "failed",
+            notes: failureNotes(shardName, "lease_violation_revert"),
+            recoveryPatch: cleanup?.recoveryPatch?.patchPath || null,
+          });
           continue;
         }
 
@@ -1087,12 +1150,19 @@ export function createSwarmHypervisor(opts) {
             integrationBranch,
             error: rebaseResult.error,
           });
-          await maybeCleanupWorktree(shardName, worker, shard, {
+          const cleanup = await maybeCleanupWorktree(shardName, worker, shard, {
             force: true,
             failureReason:
               rebaseResult.error || FAILURE_MODES.F5_MERGE_CONFLICT,
           });
           integrationFailures.push(shardName);
+          appendIntegrationReport({
+            shard: shardName,
+            strategy: "failed",
+            commits: rebaseResult.commits ?? commitEvidence.commitsAhead,
+            notes: rebaseResult.error || FAILURE_MODES.F5_MERGE_CONFLICT,
+            recoveryPatch: cleanup?.recoveryPatch?.patchPath || null,
+          });
           continue;
         }
 
@@ -1103,9 +1173,19 @@ export function createSwarmHypervisor(opts) {
           worktreePath: worker.worktreePath || null,
           integrationBranch,
           headCommit: rebaseResult.headCommit,
+          integrationStrategy: rebaseResult.strategy || "cherry-pick",
+          commits: rebaseResult.commits ?? commitEvidence.commitsAhead,
+          notes: rebaseResult.notes || "",
           completedAt: Date.now(),
         });
         integrated.push(shardName);
+        appendIntegrationReport({
+          shard: shardName,
+          strategy: rebaseResult.strategy || "cherry-pick",
+          commits: rebaseResult.commits ?? commitEvidence.commitsAhead,
+          finalSha: rebaseResult.headCommit,
+          notes: rebaseResult.notes || "",
+        });
 
         await maybeCleanupWorktree(shardName, worker, shard, {
           branchName: shardBranch,
@@ -1128,6 +1208,15 @@ export function createSwarmHypervisor(opts) {
       const skipped = preIntegrationFailures.filter(
         (name) => !integrationFailures.includes(name),
       );
+      const reported = new Set(integrationReport.map((row) => row.shard));
+      for (const shardName of failed) {
+        if (reported.has(shardName)) continue;
+        appendIntegrationReport({
+          shard: shardName,
+          strategy: "failed",
+          notes: `integration_error: ${err.message}`,
+        });
+      }
 
       eventLog.append("integration_complete", {
         integrated,
@@ -1135,6 +1224,7 @@ export function createSwarmHypervisor(opts) {
         integrationFailures,
         integrationBranch,
         skipped,
+        report: integrationReport,
         error: err.message,
       });
 
@@ -1145,6 +1235,7 @@ export function createSwarmHypervisor(opts) {
         integrationFailures,
         integrationBranch,
         skipped,
+        report: integrationReport,
         results: [...results.values()],
         partial: true,
         error: err.message,
@@ -1164,6 +1255,7 @@ export function createSwarmHypervisor(opts) {
       integrationFailures,
       integrationBranch,
       skipped,
+      report: integrationReport,
     });
 
     if (failed.length > 0 && integrated.length === 0) {
@@ -1181,6 +1273,7 @@ export function createSwarmHypervisor(opts) {
       integrationFailures,
       integrationBranch,
       skipped,
+      report: integrationReport,
       results: [...results.values()],
       partial: failed.length > 0,
     });
@@ -1198,9 +1291,10 @@ export function createSwarmHypervisor(opts) {
       failureReason = null,
     } = {},
   ) {
-    if (!worker?.worktreePath || shard?.host) return;
-    if (failureReason && keepFailedWorktrees) return;
-    if (cleanedWorktreePaths.has(worker.worktreePath)) return;
+    const outcome = { recoveryPatch: null, processCleanup: null };
+    if (!worker?.worktreePath || shard?.host) return outcome;
+    if (failureReason && keepFailedWorktrees) return outcome;
+    if (cleanedWorktreePaths.has(worker.worktreePath)) return outcome;
 
     // Best-effort: preserve any uncommitted worker changes before removing
     // the worktree. Silent on failure — must not block cleanup or mask the
@@ -1213,6 +1307,10 @@ export function createSwarmHypervisor(opts) {
           recoveryDir: join(workdir, ".codex-swarm", "recovery"),
         });
         if (preservation?.ok && !preservation.skipped) {
+          outcome.recoveryPatch = {
+            patchPath: preservation.patchPath,
+            manifestPath: preservation.manifestPath || null,
+          };
           eventLog.append("recovery_patch_saved", {
             shard: shardName,
             worktreePath: worker.worktreePath,
@@ -1236,6 +1334,7 @@ export function createSwarmHypervisor(opts) {
         runId: plan?.runId || runId,
         shardName,
       });
+      outcome.processCleanup = processCleanup;
       worker.processCleanup = processCleanup;
       recordProcessCleanup(processCleanup);
       eventLog.append("process_cleanup", {
@@ -1275,6 +1374,8 @@ export function createSwarmHypervisor(opts) {
         error: err.message,
       });
     }
+
+    return outcome;
   }
 
   /**
@@ -1387,6 +1488,7 @@ export function createSwarmHypervisor(opts) {
         integrationFailures: [...integrationPromiseState.integrationFailures],
         skipped: [...integrationPromiseState.skipped],
         integrationBranch: integrationPromiseState.integrationBranch,
+        report: integrationPromiseState.report.map((row) => ({ ...row })),
         processCleanup: Object.freeze({
           totalKilled: integrationPromiseState.processCleanup.totalKilled,
           byCategory: Object.freeze({

package/hub/team/swarm-locks.mjs

@@ -15,12 +15,12 @@ const LOCK_TTL_MS = 10 * 60_000; // 10 minutes default TTL
 // override via validateChanges options.sensitiveDeny.
 //
 // Paths use POSIX separators (matches normalizePath output).
-const SENSITIVE_PATH_PREFIXES = [
+export const SENSITIVE_PATH_PREFIXES = [
   ".claude-plugin/",
   "bin/",
   ".github/workflows/",
 ];
-const SENSITIVE_PATH_FILES = [
+export const SENSITIVE_PATH_FILES = [
   ".gitignore",
   ".npmignore",
   "package.json",
@@ -28,6 +28,11 @@ const SENSITIVE_PATH_FILES = [
   "biome.json",
 ];
 
+export const DEFAULT_SENSITIVE_DENY = Object.freeze({
+  prefixes: Object.freeze([...SENSITIVE_PATH_PREFIXES]),
+  files: Object.freeze([...SENSITIVE_PATH_FILES]),
+});
+
 /**
  * Swarm lock manager factory.
  * @param {object} [opts]

package/hub/team/swarm-preflight.mjs

@@ -0,0 +1,317 @@
+// hub/team/swarm-preflight.mjs — PRD swarm preflight report/gate (#188)
+// Predicts launch-time blockers before any worker session or worktree spawn.
+
+import { resolve } from "node:path";
+import { readHosts, resolveHost } from "../lib/hosts-compat.mjs";
+import { whichCommand } from "../platform.mjs";
+import { MCP_CATALOG } from "./mcp-selector.mjs";
+import { DEFAULT_SENSITIVE_DENY } from "./swarm-locks.mjs";
+import { planSwarm } from "./swarm-planner.mjs";
+
+const AGENT_COMMANDS = Object.freeze({
+  codex: "codex",
+  gemini: "gemini",
+  claude: "claude",
+});
+
+function unique(values) {
+  return [...new Set(values.filter(Boolean))];
+}
+
+function normalizePath(filePath) {
+  return String(filePath || "")
+    .replace(/\\/g, "/")
+    .replace(/^\.\//u, "");
+}
+
+function isSensitiveFile(filePath, sensitiveDeny = DEFAULT_SENSITIVE_DENY) {
+  const path = normalizePath(filePath);
+  const files = new Set(sensitiveDeny.files || []);
+  const prefixes = sensitiveDeny.prefixes || [];
+  return files.has(path) || prefixes.some((prefix) => path.startsWith(prefix));
+}
+
+function planToJson(plan) {
+  return {
+    totalShards: plan.shards.length,
+    shards: plan.shards.map((s) => ({
+      name: s.name,
+      agent: s.agent,
+      host: s.host || null,
+      files: [...s.files],
+      mcp: [...s.mcp],
+      depends: [...s.depends],
+      critical: s.critical,
+    })),
+    leaseMap: Object.fromEntries(plan.leaseMap),
+    mcpManifest: Object.fromEntries(plan.mcpManifest),
+    mergeOrder: [...plan.mergeOrder],
+    criticalShards: [...plan.criticalShards],
+    conflicts: [...plan.conflicts],
+    remoteSuggestion: plan.remoteSuggestion,
+  };
+}
+
+function makeCheck(name, ok, details = {}) {
+  return { name, ok: Boolean(ok), ...details };
+}
+
+function buildLeaseTable(plan, repoRoot) {
+  return plan.shards.map((shard) => ({
+    shard: shard.name,
+    host: shard.host || null,
+    worktreePath: resolve(repoRoot, ".codex-swarm", `wt-${shard.name}`),
+    files: [...shard.files],
+  }));
+}
+
+function checkSensitive(plan, sensitiveDeny) {
+  const matches = [];
+  for (const shard of plan.shards) {
+    for (const file of shard.files) {
+      if (!isSensitiveFile(file, sensitiveDeny)) continue;
+      matches.push({
+        shard: shard.name,
+        file,
+        kind: "sensitive-planned-lease",
+        severity: "warning",
+      });
+    }
+  }
+  return makeCheck("sensitiveDeny", true, { matches });
+}
+
+function checkHosts(plan, repoRoot) {
+  const registry = readHosts(repoRoot);
+  const missing = [];
+  const capabilityWarnings = [];
+
+  for (const shard of plan.shards) {
+    if (!shard.host) continue;
+    const resolvedHost = resolveHost(shard.host, repoRoot);
+    if (!resolvedHost) {
+      missing.push({ shard: shard.name, host: shard.host });
+      continue;
+    }
+    const capabilities = resolvedHost.host.capabilities || [];
+    if (shard.agent && !capabilities.includes(shard.agent)) {
+      capabilityWarnings.push({
+        shard: shard.name,
+        host: shard.host,
+        agent: shard.agent,
+        capabilities,
+      });
+    }
+  }
+
+  return makeCheck("hosts", missing.length === 0, {
+    registryPath: registry.path,
+    missing,
+    warnings: capabilityWarnings,
+  });
+}
+
+function checkLocalWorkerClis(plan, deps = {}) {
+  const which = deps.whichCommand || whichCommand;
+  const missing = [];
+  const present = [];
+  const checked = new Map();
+
+  for (const shard of plan.shards) {
+    if (shard.host) continue;
+    const command = AGENT_COMMANDS[shard.agent] || shard.agent;
+    if (!command) {
+      missing.push({ shard: shard.name, agent: shard.agent, command: null });
+      continue;
+    }
+    if (!checked.has(command)) {
+      checked.set(command, which(command, deps.whichOptions || {}));
+    }
+    const path = checked.get(command);
+    if (path)
+      present.push({ shard: shard.name, agent: shard.agent, command, path });
+    else missing.push({ shard: shard.name, agent: shard.agent, command });
+  }
+
+  return makeCheck("workerCli", missing.length === 0, { present, missing });
+}
+
+function checkMcp(plan) {
+  const catalog = new Map(MCP_CATALOG.map((entry) => [entry.name, entry]));
+  const unknown = [];
+  const incompatible = [];
+
+  for (const shard of plan.shards) {
+    for (const server of shard.mcp) {
+      const entry = catalog.get(server);
+      if (!entry) {
+        unknown.push({ shard: shard.name, server });
+        continue;
+      }
+      if (
+        ["codex", "gemini"].includes(shard.agent) &&
+        !entry.cli.includes(shard.agent)
+      ) {
+        incompatible.push({
+          shard: shard.name,
+          agent: shard.agent,
+          server,
+          supportedCli: [...entry.cli],
+        });
+      }
+    }
+  }
+
+  return makeCheck("mcp", incompatible.length === 0, { unknown, incompatible });
+}
+
+function collectMessages(checks) {
+  const errors = [];
+  const warnings = [];
+
+  const leases = checks.leases;
+  for (const conflict of leases.conflicts || []) {
+    errors.push(
+      `lease conflict: ${conflict.file} assigned to ${conflict.shards.join(", ")}`,
+    );
+  }
+
+  const hosts = checks.hosts;
+  for (const missing of hosts.missing || []) {
+    errors.push(
+      `missing host: shard ${missing.shard} references ${missing.host}`,
+    );
+  }
+  for (const warn of hosts.warnings || []) {
+    warnings.push(
+      `host capability warning: ${warn.host} does not advertise ${warn.agent} for shard ${warn.shard}`,
+    );
+  }
+
+  const workerCli = checks.workerCli;
+  for (const missing of workerCli.missing || []) {
+    errors.push(
+      `missing local worker CLI: shard ${missing.shard} requires ${missing.command || missing.agent}`,
+    );
+  }
+
+  const mcp = checks.mcp;
+  for (const item of mcp.incompatible || []) {
+    errors.push(
+      `MCP incompatibility: ${item.server} is not supported by ${item.agent} for shard ${item.shard}`,
+    );
+  }
+  for (const item of mcp.unknown || []) {
+    warnings.push(
+      `unknown MCP server: ${item.server} requested by shard ${item.shard}`,
+    );
+  }
+
+  const sensitive = checks.sensitiveDeny;
+  for (const item of sensitive.matches || []) {
+    warnings.push(
+      `sensitive path planned lease: ${item.file} owned by shard ${item.shard}`,
+    );
+  }
+
+  return { errors: unique(errors), warnings: unique(warnings) };
+}
+
+/**
+ * Build a no-side-effect preflight report for a swarm PRD.
+ *
+ * @param {string} prdPath
+ * @param {object} [opts]
+ * @param {string} [opts.repoRoot]
+ * @param {object} [opts.deps]
+ * @returns {object}
+ */
+export function runSwarmPreflight(prdPath, opts = {}) {
+  const repoRoot = opts.repoRoot || process.cwd();
+  const absPrd = resolve(prdPath);
+  const sensitiveDeny = opts.sensitiveDeny || DEFAULT_SENSITIVE_DENY;
+  let plan;
+
+  try {
+    plan = (opts.deps?.planSwarm || planSwarm)(absPrd, { repoRoot });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      ok: false,
+      verdict: "no-go",
+      prdPath: absPrd,
+      repoRoot,
+      checks: {
+        plan: makeCheck("plan", false, { error: message }),
+      },
+      errors: [message],
+      warnings: [],
+      plan: null,
+      leaseTable: [],
+    };
+  }
+
+  const checks = {
+    plan: makeCheck("plan", true),
+    leases: makeCheck("leases", plan.conflicts.length === 0, {
+      conflicts: [...plan.conflicts],
+    }),
+    sensitiveDeny: checkSensitive(plan, sensitiveDeny),
+    hosts: checkHosts(plan, repoRoot),
+    workerCli: checkLocalWorkerClis(plan, opts.deps),
+    mcp: checkMcp(plan),
+  };
+  const { errors, warnings } = collectMessages(checks);
+  const ok = Object.values(checks).every((check) => check.ok);
+
+  return {
+    ok,
+    verdict: ok ? "go" : "no-go",
+    prdPath: absPrd,
+    repoRoot,
+    checks,
+    errors,
+    warnings,
+    plan: planToJson(plan),
+    leaseTable: buildLeaseTable(plan, repoRoot),
+  };
+}
+
+export function formatPreflightReport(report) {
+  const lines = [`SWARM PREFLIGHT: ${report.verdict.toUpperCase()}`];
+
+  if (report.plan) {
+    lines.push(`PRD: ${report.prdPath}`);
+    lines.push(`Shards: ${report.plan.totalShards}`);
+    lines.push("");
+    lines.push("Lease table:");
+    for (const lease of report.leaseTable) {
+      const host = lease.host ? ` @${lease.host}` : "";
+      lines.push(`  - ${lease.shard}${host}`);
+      lines.push(`    worktree: ${lease.worktreePath}`);
+      lines.push(
+        `    files: ${lease.files.length ? lease.files.join(", ") : "(none)"}`,
+      );
+    }
+  }
+
+  lines.push("");
+  lines.push("Checks:");
+  for (const [name, check] of Object.entries(report.checks || {})) {
+    lines.push(`  ${check.ok ? "✓" : "✗"} ${name}`);
+  }
+
+  if (report.errors?.length) {
+    lines.push("");
+    lines.push("Blocking errors:");
+    for (const error of report.errors) lines.push(`  - ${error}`);
+  }
+
+  if (report.warnings?.length) {
+    lines.push("");
+    lines.push("Warnings:");
+    for (const warning of report.warnings) lines.push(`  - ${warning}`);
+  }
+
+  return `${lines.join("\n")}\n`;
+}