fix(FN-3610): isolate test home for changed-package test runs

- Create a disposable HOME/USERPROFILE env for scripts/test-changed.mjs execution
- Run isolation guard checks with the same isolated env, including cache-hit no-op paths
- Clean up temp HOME after test execution to avoid residue
- Update test coverage and contributing docs for the shared isolation behavior

Fusion-Task-Id: FN-3610

scripts/__tests__/check-test-isolation.test.mjs

@@ -3,7 +3,7 @@ import assert from "node:assert/strict";
 import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
-import { spawnSync } from "node:child_process";
+import { spawnSync, spawn } from "node:child_process";
 
 const scriptPath = path.resolve("scripts/check-test-isolation.mjs");
 
@@ -82,3 +82,36 @@ test("fails when protected .fusion existence changes after baseline", () => {
     assert.match(after.stderr, /protected live \.fusion data changed/i);
   });
 });
+
+test("passes when HOME .fusion is externally active during baseline and check", () => {
+  withFixture(({ cwd, home }) => {
+    const churnScript = `
+      const fs = require("node:fs");
+      const path = require("node:path");
+      const home = process.argv[2];
+      const target = path.join(home, ".fusion", "external-churn.txt");
+      let n = 0;
+      const timer = setInterval(() => {
+        fs.writeFileSync(target, String(n++));
+      }, 120);
+      setTimeout(() => {
+        clearInterval(timer);
+        process.exit(0);
+      }, 3500);
+    `;
+
+    const churn = spawn(process.execPath, ["-e", churnScript, home], {
+      cwd,
+      env: { ...process.env, HOME: home, USERPROFILE: home },
+      stdio: "ignore",
+    });
+
+    const before = runScript(["--before"], { cwd, home });
+    assert.equal(before.status, 0);
+    const after = runScript([], { cwd, home });
+    assert.equal(after.status, 0);
+
+    churn.kill("SIGTERM");
+    rmSync(path.join(home, ".fusion", "external-churn.txt"), { force: true });
+  });
+});

scripts/__tests__/plugin-authoring-docs.test.mjs

@@ -26,7 +26,7 @@ const expectedSections = [
   "Example Plugins",
   "Registering Skills",
   "Registering Workflow Steps",
-  "Plugin Prompt Contributions",
+  "Contributing Prompt Modifications",
   "Plugin Binary Setup Hooks",
 ];
 

scripts/__tests__/test-changed.test.mjs

@@ -19,6 +19,7 @@ import {
   cacheFilePath,
   shouldRunIsolationGuard,
   defaultTestWorkerBudget,
+  createIsolatedHomeEnv,
 } from "../test-changed.mjs";
 
 import { mkdirSync, writeFileSync, mkdtempSync, rmSync } from "node:fs";
@@ -625,3 +626,16 @@ test("defaultTestWorkerBudget: uses CPU-aware defaults and clamps concurrency",
   assert.ok(budget.totalWorkers <= 12);
   assert.equal(budget.concurrency, budget.totalWorkers);
 });
+
+test("createIsolatedHomeEnv: returns temp HOME/USERPROFILE pair without mutating input", () => {
+  const baseEnv = { PATH: process.env.PATH || "" };
+  const { env, isolatedHome } = createIsolatedHomeEnv(baseEnv);
+
+  assert.equal(env.HOME, isolatedHome);
+  assert.equal(env.USERPROFILE, isolatedHome);
+  assert.equal(baseEnv.HOME, undefined);
+  assert.equal(baseEnv.USERPROFILE, undefined);
+  assert.match(isolatedHome, /fusion-test-home-root-/);
+
+  rmSync(isolatedHome, { recursive: true, force: true });
+});

scripts/test-changed.mjs

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 
-import { readFileSync, readdirSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
+import { readFileSync, readdirSync, writeFileSync, mkdirSync, renameSync, mkdtempSync, rmSync, realpathSync } from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { createHash } from "node:crypto";
-import { cpus } from "node:os";
+import { cpus, tmpdir } from "node:os";
 import { ensureTestArtifacts } from "./ensure-test-artifacts.mjs";
 
 const currentFilePath = fileURLToPath(import.meta.url);
@@ -37,10 +37,10 @@ function run(command, commandArgs, options = {}) {
   }
 }
 
-function runIsolationCheck(before = false) {
+function runIsolationCheck(before = false, env = process.env) {
   const args = [checkIsolationScript];
   if (before) args.push("--before");
-  run(process.execPath, args);
+  run(process.execPath, args, { env });
 }
 
 export function shouldRunIsolationGuard(env = process.env) {
@@ -49,11 +49,12 @@ export function shouldRunIsolationGuard(env = process.env) {
 
 function runMaybeIsolated(command, commandArgs, options = {}) {
   const enabled = shouldRunIsolationGuard();
-  if (enabled) runIsolationCheck(true);
+  const env = options.env ?? process.env;
+  if (enabled) runIsolationCheck(true, env);
   try {
     run(command, commandArgs, options);
   } finally {
-    if (enabled) runIsolationCheck(false);
+    if (enabled) runIsolationCheck(false, env);
   }
 }
 
@@ -493,16 +494,31 @@ export function defaultTestWorkerBudget(env = process.env) {
 
 const { totalWorkers, concurrency } = defaultTestWorkerBudget(process.env);
 
+export function createIsolatedHomeEnv(env = process.env) {
+  const isolatedHome = realpathSync(mkdtempSync(path.join(tmpdir(), "fusion-test-home-root-")));
+  const nextEnv = {
+    ...env,
+    HOME: isolatedHome,
+    USERPROFILE: isolatedHome,
+  };
+
+  if (process.platform === "win32") {
+    const match = isolatedHome.match(/^([A-Za-z]:)(.*)$/);
+    if (match) {
+      nextEnv.HOMEDRIVE = match[1];
+      nextEnv.HOMEPATH = match[2] || "\\";
+    }
+  }
+
+  return { env: nextEnv, isolatedHome };
+}
+
 const fullSuiteEnv = {
   ...process.env,
   FUSION_TEST_TOTAL_WORKERS: process.env.FUSION_TEST_TOTAL_WORKERS || String(totalWorkers),
   FUSION_TEST_CONCURRENCY: process.env.FUSION_TEST_CONCURRENCY || String(concurrency),
 };
 
-function runFullSuite(forwardedArgs) {
-  runMaybeIsolated("pnpm", [`-r`, `--workspace-concurrency=${workspaceConcurrency}`, "test", ...forwardedArgs], { env: fullSuiteEnv });
-}
-
 export function decideExecutionPlan({
   forceFullSuite,
   comparisonBase,
@@ -536,6 +552,10 @@ export function main(argv = process.argv.slice(2)) {
   run("pnpm", ["sync:fusion-skill:check"]);
   ensureTestArtifacts(rootDir);
 
+  const { env: isolatedHomeEnv, isolatedHome } = createIsolatedHomeEnv(fullSuiteEnv);
+
+  try {
+
   const baseBranch = getBaseBranch();
   const comparisonBase = detectComparisonBase(baseBranch);
   const changedFiles = comparisonBase ? changedFilesSince(comparisonBase) : null;
@@ -567,7 +587,7 @@ export function main(argv = process.argv.slice(2)) {
       console.log("[test-changed] no affected workspace package resolved; running full suite.");
     }
 
-    runFullSuite(forwardedArgs);
+    runMaybeIsolated("pnpm", [`-r`, `--workspace-concurrency=${workspaceConcurrency}`, "test", ...forwardedArgs], { env: isolatedHomeEnv });
     return;
   }
 
@@ -582,8 +602,8 @@ export function main(argv = process.argv.slice(2)) {
       `[test-changed] all changed packages are cache-fresh (${cachedPackages.join(", ")}); nothing to run.`,
     );
     if (shouldRunIsolationGuard()) {
-      runIsolationCheck(true);
-      runIsolationCheck(false);
+      runIsolationCheck(true, isolatedHomeEnv);
+      runIsolationCheck(false, isolatedHomeEnv);
     }
     return;
   }
@@ -594,10 +614,13 @@ export function main(argv = process.argv.slice(2)) {
     console.log(`[test-changed] skipping cached packages: ${cachedPackages.join(", ")}`);
   }
 
-  runMaybeIsolated("pnpm", [...filterArgs, `--workspace-concurrency=${workspaceConcurrency}`, "test", ...forwardedArgs], { env: fullSuiteEnv });
+  runMaybeIsolated("pnpm", [...filterArgs, `--workspace-concurrency=${workspaceConcurrency}`, "test", ...forwardedArgs], { env: isolatedHomeEnv });
 
   // Tests passed — record in cache (never cache failures; process.exit on failure above).
   recordCachePass(activePackages, packageDirByName, { noCache });
+  } finally {
+    rmSync(isolatedHome, { recursive: true, force: true });
+  }
 }
 
 if (process.argv[1] && path.resolve(process.argv[1]) === currentFilePath) {