feat(FN-4772): complete Step 2 — add hybrid executor gate

Fusion-Task-Id: FN-4772
Fusion-Task-Lineage: d296e96a-fe44-4896-928a-fa44da62b41a

packages/engine/src/__tests__/hybrid-executor-gate.test.ts

@@ -0,0 +1,75 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { CentralCore } from "@fusion/core";
+import { shouldUseHybridExecutor } from "../hybrid-executor-gate.js";
+
+function createMockCentralCore(overrides?: {
+  listNodes?: () => Promise<Array<{ id: string; type: "local" | "remote" }>>;
+  listProjects?: () => Promise<Array<{ status: "active" | "initializing" | "paused" | "errored" }>>;
+}): CentralCore {
+  return {
+    listNodes: overrides?.listNodes ?? (async () => [{ id: "local", type: "local" }]),
+    listProjects: overrides?.listProjects ?? (async () => [{ status: "active" }]),
+  } as unknown as CentralCore;
+}
+
+describe("shouldUseHybridExecutor", () => {
+  const originalEnv = process.env.FUSION_HYBRID_EXECUTOR;
+
+  afterEach(() => {
+    if (originalEnv === undefined) {
+      delete process.env.FUSION_HYBRID_EXECUTOR;
+    } else {
+      process.env.FUSION_HYBRID_EXECUTOR = originalEnv;
+    }
+  });
+
+  it("enables via env override=1", async () => {
+    process.env.FUSION_HYBRID_EXECUTOR = "1";
+    const decision = await shouldUseHybridExecutor(createMockCentralCore());
+    expect(decision).toEqual({ enabled: true, reason: "env-override" });
+  });
+
+  it("disables via env override=0", async () => {
+    process.env.FUSION_HYBRID_EXECUTOR = "0";
+    const decision = await shouldUseHybridExecutor(createMockCentralCore());
+    expect(decision).toEqual({ enabled: false, reason: "env-override" });
+  });
+
+  it("enables for multi-node", async () => {
+    delete process.env.FUSION_HYBRID_EXECUTOR;
+    const decision = await shouldUseHybridExecutor(
+      createMockCentralCore({
+        listNodes: async () => [
+          { id: "local", type: "local" },
+          { id: "remote", type: "remote" },
+        ],
+      }),
+    );
+    expect(decision).toEqual({ enabled: true, reason: "multi-node" });
+  });
+
+  it("enables for multi-project active/initializing", async () => {
+    delete process.env.FUSION_HYBRID_EXECUTOR;
+    const decision = await shouldUseHybridExecutor(
+      createMockCentralCore({
+        listProjects: async () => [{ status: "active" }, { status: "initializing" }],
+      }),
+    );
+    expect(decision).toEqual({ enabled: true, reason: "multi-project" });
+  });
+
+  it("disables for single local project", async () => {
+    delete process.env.FUSION_HYBRID_EXECUTOR;
+    const decision = await shouldUseHybridExecutor(createMockCentralCore());
+    expect(decision).toEqual({ enabled: false, reason: "single-project-local-only" });
+  });
+
+  it("disables when central APIs throw", async () => {
+    delete process.env.FUSION_HYBRID_EXECUTOR;
+    const centralCore = createMockCentralCore({
+      listNodes: vi.fn().mockRejectedValue(new Error("boom")),
+    });
+    const decision = await shouldUseHybridExecutor(centralCore);
+    expect(decision).toEqual({ enabled: false, reason: "central-unavailable" });
+  });
+});

packages/engine/src/hybrid-executor-gate.ts

@@ -0,0 +1,42 @@
+import type { CentralCore } from "@fusion/core";
+
+export interface HybridExecutorGateDecision {
+  enabled: boolean;
+  reason: string;
+}
+
+function parseEnvOverride(value: string | undefined): HybridExecutorGateDecision | null {
+  if (value === "1") {
+    return { enabled: true, reason: "env-override" };
+  }
+
+  if (value === "0") {
+    return { enabled: false, reason: "env-override" };
+  }
+
+  return null;
+}
+
+export async function shouldUseHybridExecutor(centralCore: CentralCore): Promise<HybridExecutorGateDecision> {
+  const envOverride = parseEnvOverride(process.env.FUSION_HYBRID_EXECUTOR);
+  if (envOverride) {
+    return envOverride;
+  }
+
+  try {
+    const nodes = await centralCore.listNodes();
+    if (nodes.length > 1) {
+      return { enabled: true, reason: "multi-node" };
+    }
+
+    const projects = await centralCore.listProjects();
+    const liveProjects = projects.filter((project) => project.status === "active" || project.status === "initializing");
+    if (liveProjects.length > 1) {
+      return { enabled: true, reason: "multi-project" };
+    }
+
+    return { enabled: false, reason: "single-project-local-only" };
+  } catch {
+    return { enabled: false, reason: "central-unavailable" };
+  }
+}

packages/engine/src/index.ts

@@ -257,6 +257,7 @@ export {
   type HybridExecutorOptions,
   type HybridExecutorEvents,
 } from "./hybrid-executor.js";
+export { shouldUseHybridExecutor, type HybridExecutorGateDecision } from "./hybrid-executor-gate.js";
 export { applyUnavailableNodePolicy, type PolicyDecision } from "./node-routing-policy.js";
 export { PeerExchangeService, type PeerExchangeServiceOptions, type SyncResult } from "./peer-exchange-service.js";
 export {