chore(dev): allow explicit test worker budgets and document pinned installs (#921)

Author: tt-a1i

CONTRIBUTING.md

@@ -70,6 +70,11 @@ bun run check
 bun run test
 ```
 
+The Node and UI runners default to at most four concurrent test files. On a
+machine with at least eight available CPUs, `OPENPI_TEST_WORKERS=8 bun run test`
+uses eight workers. For a memory-constrained run, set it to one or two.
+Windows process-isolated tests always run one file at a time.
+
 Green automation only proves the code, type, and test contracts. When a change touches the runtime or the UI, also complete the matching smoke in a real, `/reload`ed Pi:
 
 - Tool or lifecycle changes: actually trigger the success, failure, and termination paths in normal tool mode;

extensions/subagents/docs/effect-v4-notes.md

@@ -16,14 +16,16 @@
 
 ## Install
 
-```bash
-npm install effect@beta @effect/platform-node@beta
-```
+Use the repository root `package.json` and lockfile for the current Effect versions.
+Install the pinned development dependencies from the repository root with
+`bun install --frozen-lockfile`. The examples below retain their historical beta.98
+verification; they are not an instruction to install that version.
 
 Big structural facts:
 
-- **One version number for everything.** All ecosystem packages release together at
-  `4.0.0-beta.N`. `@effect/platform-node` must match `effect` exactly.
+- **Use the repository's tested version cohort.** The root manifest pins Effect packages
+  together to avoid prerelease dependency drift during packed npm installs; see
+  [issue #533](https://github.com/openpi-dev/openpi/issues/533).
 - **`@effect/platform` is gone — merged into core `effect`.** `FileSystem`, `Path`,
   `PlatformError`, `Terminal`, `Stdio` are now top-level `effect` modules.
   `@effect/platform-node` remains as the Node *implementation* package.

scripts/run-tests.mjs

@@ -32,7 +32,21 @@ if (nodeTests.length === 0 || vitestTests.length === 0) {
 
 // Process and jsdom fixtures both need headroom. Bound file-level overlap
 // instead of letting cold loaders and DOM work compete for every core.
-const concurrency = Math.max(1, Math.min(4, availableParallelism() - 1));
+const availableWorkers = availableParallelism();
+const requestedWorkers = process.env.OPENPI_TEST_WORKERS;
+const concurrency =
+  requestedWorkers === undefined
+    ? Math.max(1, Math.min(4, availableWorkers - 1))
+    : Number(requestedWorkers);
+if (
+  !Number.isInteger(concurrency) ||
+  concurrency < 1 ||
+  concurrency > availableWorkers
+) {
+  throw new Error(
+    `OPENPI_TEST_WORKERS must be an integer between 1 and ${availableWorkers}.`,
+  );
+}
 
 function runNodeTests(files, options = []) {
   if (files.length === 0) return 0;

tests/scripts/run-tests.test.ts

@@ -7,7 +7,7 @@ import {
   rmSync,
   writeFileSync,
 } from "node:fs";
-import { tmpdir } from "node:os";
+import { availableParallelism, tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import test from "node:test";
 
@@ -59,7 +59,9 @@ function fixture() {
     assert.equal(process.argv[2], "run");
     const args = process.argv.slice(3);
     const workers = Number(args.find((arg) => arg.startsWith("--maxWorkers="))?.split("=")[1]);
-    assert.ok(Number.isInteger(workers) && workers >= 1 && workers <= 4);
+    assert.ok(Number.isInteger(workers) && workers >= 1);
+    if (process.env.EXPECT_WORKERS) assert.equal(workers, Number(process.env.EXPECT_WORKERS));
+    else assert.ok(workers <= 4);
     const files = args.filter((arg) => !arg.startsWith("--"));
     assert.equal(files.length, 1);
     assert.ok(files[0].endsWith("sample.spec.ts"));
@@ -69,8 +71,17 @@ function fixture() {
   );
   return {
     root,
-    run(args: string[] = [], failSuite = "") {
-      const env: NodeJS.ProcessEnv = { ...process.env, FAIL_SUITE: failSuite };
+    run(
+      args: string[] = [],
+      failSuite = "",
+      overrides: NodeJS.ProcessEnv = {},
+    ) {
+      const env: NodeJS.ProcessEnv = {
+        ...process.env,
+        FAIL_SUITE: failSuite,
+      };
+      delete env.OPENPI_TEST_WORKERS;
+      Object.assign(env, overrides);
       // Start a fresh test runner rather than inheriting this test worker context.
       delete env.NODE_TEST_CONTEXT;
       return spawnSync(process.execPath, ["scripts/run-tests.mjs", ...args], {
@@ -210,3 +221,35 @@ test("invalid selection and empty discovery fail before running a partial suite"
     runner.dispose();
   }
 });
+
+test("local worker override is validated before running tests", () => {
+  const runner = fixture();
+  try {
+    const workers = String(Math.min(5, availableParallelism()));
+    const valid = runner.run(["ui"], "", {
+      OPENPI_TEST_WORKERS: workers,
+      EXPECT_WORKERS: workers,
+    });
+    assert.equal(valid.status, 0, valid.stderr || valid.stdout);
+    const node = runner.run(["node"], "", { OPENPI_TEST_WORKERS: "1" });
+    assert.equal(node.status, 0, node.stderr || node.stdout);
+    for (const value of [
+      "0",
+      "-1",
+      "1.5",
+      "2junk",
+      "",
+      "9007199254740992",
+      String(availableParallelism() + 1),
+    ]) {
+      const invalid = runner.run([], "", {
+        OPENPI_TEST_WORKERS: value,
+      });
+      assert.notEqual(invalid.status, 0);
+      assert.match(invalid.stderr, /OPENPI_TEST_WORKERS must be an integer/);
+      assert.equal(invalid.stdout.includes("marker"), false);
+    }
+  } finally {
+    runner.dispose();
+  }
+});