@effected/github-actions 0.13.0 → 0.13.2

package/PackageManagerInstaller.js

@@ -1,9 +1,13 @@
 import { ActionEnvironment } from "./ActionEnvironment.js";
+import { unstubbed } from "./internal/unstubbed.js";
+import { digestFileHex } from "./internal/digest.js";
+import { isWindowsRunner, toolCacheRoot } from "./internal/runner.js";
+import { typeAt } from "./internal/fsProbe.js";
+import { PNPM_EXE_PREFIX, detectMusl, isNodeScript, pnpmExeTarget, strongestSri } from "./internal/pnpmExe.js";
 import { ToolInstaller } from "./ToolInstaller.js";
-import { Context, Effect, FileSystem, Layer, Option, Path, Schema, Stream } from "effect";
-import { createHash } from "node:crypto";
+import { Context, Effect, FileSystem, Layer, Option, Path, Schema } from "effect";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
-import { PackageManagerPinName } from "@effected/npm";
+import { DEFAULT_REGISTRY, PackageManagerPinName } from "@effected/npm";
 
 //#region src/PackageManagerInstaller.ts
 /**
@@ -19,9 +23,11 @@ var PackageManagerInstallerError = class extends Schema.TaggedError()("PackageMa
 	* entry). `integrityMismatch` — the downloaded artifact does not hash to
 	* what the pin declares; nothing was cached. `integrityMissing` — the pin
 	* carries no integrity and the caller asked for `requireIntegrity`.
-	* `unsupportedPlatform` — bun publishes no build for this runner's
-	* OS/architecture pair. `layoutUnexpected` — the artifact extracted, but
-	* its contents are not shaped like the package manager it claims to be.
+	* `unsupportedPlatform` — no build exists for this runner's
+	* OS/architecture pair: bun publishes none, or pnpm 12 ships no
+	* `@pnpm/exe.*` native binary for it. `layoutUnexpected` — the artifact
+	* extracted, but its contents are not shaped like the package manager it
+	* claims to be.
 	*/
 	reason: Schema.Literals([
 		"downloadFailed",
@@ -90,10 +96,14 @@ var AmbientPackageManager = class extends Schema.Class("AmbientPackageManager")(
 * on Windows); for bun it is the entry directory itself, because the cached
 * `bun` binary is directly executable and a shim would add nothing but a
 * fork. `bins` still maps each published bin name to the underlying entry —
-* a Node script to run with `node` for npm/pnpm/yarn, the native binary for
-* bun. Calling `addPath` remains deliberately the consumer's move, and note
-* that `addPath` targets *subsequent* steps: a same-process probe must use
-* the absolute paths in `bins` or `binDir`.
+* a Node script to run with `node` for npm, yarn and pnpm 11 and earlier; an
+* executable to run directly for bun and for pnpm 12+, whose `pnpm` is the
+* host's native binary (overlaid onto the cached wrapper the way pnpm's own
+* install script does) and whose `pn`/`pnpx`/`pnx` are shell aliases of it.
+* Each shim already applies that distinction. Calling `addPath` remains
+* deliberately the consumer's move, and note that `addPath` targets
+* *subsequent* steps: a same-process probe must use the absolute paths in
+* `bins` or `binDir`.
 *
 * @public
 */
@@ -130,16 +140,26 @@ var CachedPackageManager = class extends Schema.Class("CachedPackageManager")({
 * @public
 */
 const InstalledPackageManager = Schema.Union([AmbientPackageManager, CachedPackageManager]);
-const DEFAULT_REGISTRY = "https://registry.npmjs.org";
 /** The shim directory name inside a cached npm-registry-manager entry. */
 const SHIM_DIR = ".bin";
 /**
-* The POSIX shim body: an `exec` wrapper so the shim's process *becomes*
-* node, and `"$@"` so arguments survive quoting intact.
+* The POSIX shim body: an `exec` wrapper so the shim's process *becomes* the
+* target, and `"$@"` so arguments survive quoting intact. A Node script
+* (`.js`/`.mjs`/`.cjs`) runs under `node`; anything else — pnpm 12's native
+* binary, its `#!/bin/sh` alias scripts — is exec'd directly, because handing
+* a shell script or a Mach-O to node is exactly the "Invalid or unexpected
+* token" failure this rule exists to prevent.
 */
-const posixShim = (target) => `#!/bin/sh\nexec node "${target}" "$@"\n`;
-/** The Windows shim body, CRLF-terminated as cmd expects. */
-const cmdShim = (target) => `@echo off\r\nnode "${target}" %*\r\n`;
+const posixShim = (target) => isNodeScript(target) ? `#!/bin/sh\nexec node "${target}" "$@"\n` : `#!/bin/sh\nexec "${target}" "$@"\n`;
+/** The Windows shim body, CRLF-terminated as cmd expects; same node-vs-direct rule. */
+const cmdShim = (target) => isNodeScript(target) ? `@echo off\r\nnode "${target}" %*\r\n` : `@echo off\r\n"${target}" %*\r\n`;
+/** The bin names pnpm's wrapper publishes, every one of which becomes the native binary on Windows. */
+const PNPM_NATIVE_BIN_NAMES = [
+	"pnpm",
+	"pn",
+	"pnpx",
+	"pnx"
+];
 /**
 * The bun release asset name for a runner platform, or `None` when bun
 * publishes no build for it.
@@ -149,9 +169,18 @@ const cmdShim = (target) => `@echo off\r\nnode "${target}" %*\r\n`;
 * bun's spelling (`macOS` → `darwin`) and the Node arch spelling to bun's
 * (`arm64` → `aarch64`).
 */
+const BUN_OS = {
+	linux: "linux",
+	macos: "darwin",
+	windows: "windows"
+};
+const BUN_CPU = {
+	x64: "x64",
+	arm64: "aarch64"
+};
 const bunTarget = (runnerOs, arch) => {
-	const os = runnerOs.toLowerCase() === "linux" ? "linux" : runnerOs.toLowerCase() === "macos" ? "darwin" : runnerOs.toLowerCase() === "windows" ? "windows" : void 0;
-	const cpu = arch === "x64" ? "x64" : arch === "arm64" ? "aarch64" : void 0;
+	const os = BUN_OS[runnerOs.toLowerCase()];
+	const cpu = BUN_CPU[arch];
 	return os === void 0 || cpu === void 0 ? Option.none() : Option.some(`bun-${os}-${cpu}`);
 };
 /**
@@ -174,7 +203,10 @@ const normalizeBins = (bin, fallbackName) => {
 	return Object.keys(entries).length === 0 ? Option.none() : Option.some(entries);
 };
 /** Map a `RUNNER_ARCH` value (`X64`, `ARM64`) onto the Node arch spelling. */
-const archFromRunner = (runnerArch) => runnerArch.toLowerCase() === "x64" ? "x64" : runnerArch.toLowerCase() === "arm64" ? "arm64" : runnerArch;
+const archFromRunner = (runnerArch) => {
+	const lowered = runnerArch.toLowerCase();
+	return lowered === "x64" || lowered === "arm64" ? lowered : runnerArch;
+};
 const make = Effect.gen(function* () {
 	const env = yield* ActionEnvironment;
 	const fs = yield* FileSystem.FileSystem;
@@ -186,11 +218,12 @@ const make = Effect.gen(function* () {
 		onNone: () => process.arch,
 		onSome: archFromRunner
 	}));
-	const windows = runnerOs.toLowerCase() === "windows";
+	const windows = yield* isWindowsRunner(env);
+	const musl = detectMusl();
 	const bunBinaryName = windows ? "bun.exe" : "bun";
 	const shimFileName = (name) => windows ? `${name}.cmd` : name;
 	const shimBody = windows ? cmdShim : posixShim;
-	const cacheRoot = yield* Effect.map(env.getOptional("RUNNER_TOOL_CACHE"), (found) => Option.getOrElse(found, () => path.join("/tmp", "runner-tool-cache")));
+	const cacheRoot = yield* toolCacheRoot(env, path);
 	const finalCachePath = (tool, version) => ToolInstaller.cachePath({
 		root: cacheRoot,
 		tool,
@@ -209,16 +242,11 @@ const make = Effect.gen(function* () {
 		cause
 	});
 	/** The hex digest of a file's bytes, streamed rather than buffered. */
-	const hashFile = (pin, file, algorithm) => Effect.suspend(() => {
-		const digest = createHash(algorithm);
-		return fs.stream(file).pipe(Stream.runForEach((chunk) => Effect.sync(() => {
-			digest.update(chunk);
-		})), Effect.map(() => digest.digest("hex")), Effect.mapError((cause) => errorFor(pin)({
-			reason: "integrityMismatch",
-			subject: file,
-			cause
-		})));
-	});
+	const hashFile = (pin, file, algorithm) => digestFileHex(fs, file, algorithm).pipe(Effect.mapError((cause) => errorFor(pin)({
+		reason: "integrityMismatch",
+		subject: file,
+		cause
+	})));
 	/**
 	* Verify a downloaded artifact against the pin's integrity, fail-closed.
 	*
@@ -250,20 +278,24 @@ const make = Effect.gen(function* () {
 	*/
 	const ambientNpmVersion = Effect.map(Effect.result(spawner.string(ChildProcess.make("npm", ["--version"]))), (result) => result._tag === "Success" ? Option.some(result.success.trim()) : Option.none());
 	const assertFile = (pin, file, subject) => Effect.gen(function* () {
-		const stat = yield* Effect.result(fs.stat(file));
-		if (stat._tag !== "Success" || stat.success.type !== "File") return yield* Effect.fail(errorFor(pin)({
+		if ((yield* typeAt(fs, file)) !== "File") return yield* Effect.fail(errorFor(pin)({
 			reason: "layoutUnexpected",
 			subject
 		}));
 	});
 	/**
-	* The bin entries a package directory publishes, from its own manifest.
+	* What a package directory's own manifest says about its entry points: the
+	* `bin` map, plus the `@pnpm/exe.*` optional dependencies that mark the
+	* pnpm 12 native-binary layout (empty for every other manager and version).
 	*
 	* Read from the artifact rather than hardcoded per manager, because the
 	* layouts genuinely move — corepack's own table has pnpm's entry at
-	* `bin/pnpm.cjs` through v10 and `bin/pnpm.mjs` from v11.
+	* `bin/pnpm.cjs` through v10 and `bin/pnpm.mjs` from v11, and from v12 the
+	* `pnpm` bin is a placeholder for a native binary shipped as a separate
+	* package. Both maps are attacker-supplied bytes and are normalized to
+	* string → string before anything downstream reads them.
 	*/
-	const readPackageBins = (pin, packageDir) => Effect.gen(function* () {
+	const readPackageManifest = (pin, packageDir) => Effect.gen(function* () {
 		const manifestPath = path.join(packageDir, "package.json");
 		const raw = yield* fs.readFileString(manifestPath).pipe(Effect.mapError((cause) => errorFor(pin)({
 			reason: "layoutUnexpected",
@@ -292,8 +324,41 @@ const make = Effect.gen(function* () {
 			}));
 			yield* assertFile(pin, target, `bin ${name} (${relative}) is missing`);
 		}
-		return bins;
+		return {
+			bins,
+			nativePackages: nativePackagesOf(manifest.optionalDependencies)
+		};
 	});
+	/**
+	* The `@pnpm/exe.<target>` → version entries of an `optionalDependencies`
+	* value, and nothing else: only well-formed string pairs under that prefix
+	* survive, so a hostile or malformed map cannot smuggle a package name
+	* into a registry url.
+	*/
+	const nativePackagesOf = (optionalDependencies) => {
+		if (typeof optionalDependencies !== "object" || optionalDependencies === null) return {};
+		const entries = {};
+		for (const [name, version] of Object.entries(optionalDependencies)) if (name.startsWith("@pnpm/exe.") && typeof version === "string") entries[name] = version;
+		return entries;
+	};
+	/**
+	* pnpm's Windows overlay places the native binary as `<name>.exe` for every
+	* wrapper bin and repoints `bin` at those; this is that repoint, applied to
+	* the in-memory map (the shims and the record) rather than the manifest.
+	*/
+	const nativeWindowsBins = (bins) => Object.fromEntries(Object.entries(bins).map(([name, relative]) => PNPM_NATIVE_BIN_NAMES.includes(name) ? [name, `${relative}.exe`] : [name, relative]));
+	/**
+	* Whether a file is still pnpm's shebang-less placeholder (a `#`-led text
+	* file that is not a `#!` script) rather than the native binary meant to
+	* overlay it — the mark of an entry written by a version of this module
+	* that predates the overlay, or by a foreign writer that ran no lifecycle
+	* scripts. Anything else (a shebang, an executable's magic, an unreadable
+	* or empty file) is left to the ordinary layout checks.
+	*/
+	const isPlaceholder = (file) => Effect.scoped(Effect.flatMap(fs.open(file), (handle) => handle.readAlloc(2))).pipe(Effect.map((head) => Option.match(head, {
+		onNone: () => false,
+		onSome: (bytes) => bytes.length >= 1 && bytes[0] === 35 && bytes[1] !== 33
+	})), Effect.orElseSucceed(() => false));
 	const rootBins = (bins, directory) => Object.fromEntries(Object.entries(bins).map(([name, relative]) => [name, path.join(directory, relative)]));
 	/**
 	* Write one executable shim per bin into `<into>/.bin`, each invoking
@@ -319,35 +384,124 @@ const make = Effect.gen(function* () {
 		for (const [name, relative] of Object.entries(bins)) {
 			const shim = path.join(shimDir, shimFileName(name));
 			if (options.skipExisting) {
-				const present = yield* Effect.result(fs.stat(shim));
-				if (present._tag === "Success" && present.success.type === "File") continue;
+				if ((yield* typeAt(fs, shim)) === "File") continue;
 			}
 			yield* fs.writeFileString(shim, shimBody(path.join(finalDirectory, relative))).pipe(Effect.mapError(cacheError(shim)));
 			if (!windows) yield* fs.chmod(shim, 493).pipe(Effect.mapError(cacheError(shim)));
 		}
 	});
-	/** The record for a directory already in the cache, regenerating absent shims. */
+	/**
+	* The record for a directory already in the cache, regenerating absent
+	* shims — or `None` when the entry is a pnpm 12 wrapper whose `pnpm` bin is
+	* still the placeholder, which no shim can make runnable: the caller then
+	* reinstalls over it through the ordinary install path (ToolInstaller's
+	* swap removes the old entry and renames the complete new one into place).
+	*/
 	const cachedRecord = (pin, directory) => Effect.gen(function* () {
 		if (pin.name === "bun") {
 			const binary = path.join(directory, bunBinaryName);
 			yield* assertFile(pin, binary, `cached bun binary (${bunBinaryName}) is missing`);
-			return CachedPackageManager.make({
+			return Option.some(CachedPackageManager.make({
 				name: pin.name,
 				version: pin.version.toString(),
 				directory,
 				binDir: directory,
 				bins: { bun: binary }
-			});
+			}));
+		}
+		const manifest = yield* readPackageManifest(pin, directory);
+		let bins = manifest.bins;
+		if (Object.keys(manifest.nativePackages).length > 0) {
+			const entry = bins[pin.name];
+			if (entry !== void 0 && (yield* isPlaceholder(path.join(directory, entry)))) {
+				yield* Effect.logInfo(`The cached ${pin.name}@${pin.version.toString()} still holds pnpm's placeholder bin; reinstalling it over.`);
+				return Option.none();
+			}
+			if (windows) bins = nativeWindowsBins(bins);
 		}
-		const bins = yield* readPackageBins(pin, directory);
 		yield* writeShims(pin, directory, directory, bins, { skipExisting: true });
-		return CachedPackageManager.make({
+		return Option.some(CachedPackageManager.make({
 			name: pin.name,
 			version: pin.version.toString(),
 			directory,
 			binDir: path.join(directory, SHIM_DIR),
 			bins: rootBins(bins, directory)
+		}));
+	});
+	/**
+	* pnpm 12's native overlay, done here because the installer never runs the
+	* lifecycle script that does it upstream: pick the host's `@pnpm/exe.*`
+	* package from the wrapper's optional dependencies, fetch its tarball from
+	* the SAME registry the wrapper came from, verify it against the registry's
+	* own `dist.integrity` (fail-closed — this is a second artifact the pin
+	* never named, so there is no integrity-less posture to honor), and copy
+	* the executable over the placeholder in the STAGED wrapper, where `dist/`
+	* sits beside it as the binary expects. Answers the bins as they should be
+	* shimmed and recorded — retargeted to `.exe` on Windows, as upstream does.
+	*/
+	const overlayNativeBinary = (pin, packageDir, bins, nativePackages, registry) => Effect.gen(function* () {
+		const target = Option.getOrUndefined(pnpmExeTarget(runnerOs, arch, musl));
+		const packageName = target === void 0 ? void 0 : `${PNPM_EXE_PREFIX}${target}`;
+		const nativeVersion = packageName === void 0 ? void 0 : nativePackages[packageName];
+		if (target === void 0 || packageName === void 0 || nativeVersion === void 0) return yield* Effect.fail(errorFor(pin)({
+			reason: "unsupportedPlatform",
+			subject: `${runnerOs || "unknown"}/${arch}`
+		}));
+		if (nativeVersion !== pin.version.toString()) return yield* Effect.fail(errorFor(pin)({
+			reason: "layoutUnexpected",
+			subject: `${packageName} is pinned at ${nativeVersion}, not the wrapper's ${pin.version.toString()}`
+		}));
+		const placeholder = bins[pin.name];
+		if (placeholder === void 0) return yield* Effect.fail(errorFor(pin)({
+			reason: "layoutUnexpected",
+			subject: `package.json names no ${pin.name} bin to overlay`
+		}));
+		const packumentUrl = `${registry}/${packageName}/${nativeVersion}`;
+		const packumentFile = yield* installer.download(packumentUrl).pipe(Effect.mapError(fromInstaller(pin)));
+		const unverifiable = (cause) => errorFor(pin)({
+			reason: "integrityMismatch",
+			subject: packumentUrl,
+			...cause === void 0 ? {} : { cause }
 		});
+		const declared = (yield* fs.readFileString(packumentFile).pipe(Effect.mapError((cause) => unverifiable(cause)), Effect.flatMap((raw) => Effect.try({
+			try: () => JSON.parse(raw),
+			catch: (cause) => unverifiable(cause)
+		})))).dist?.integrity;
+		const expected = typeof declared === "string" ? Option.getOrUndefined(strongestSri(declared)) : void 0;
+		if (expected === void 0) return yield* Effect.fail(unverifiable());
+		const tarballUrl = `${registry}/${packageName}/-/exe.${target}-${nativeVersion}.tgz`;
+		const archive = yield* installer.download(tarballUrl).pipe(Effect.mapError(fromInstaller(pin)));
+		const actualHex = yield* hashFile(pin, archive, expected.algorithm);
+		if (actualHex !== expected.hex) return yield* Effect.fail(errorFor(pin)({
+			reason: "integrityMismatch",
+			subject: tarballUrl,
+			expected: `${expected.algorithm}.${expected.hex}`,
+			actual: `${expected.algorithm}.${actualHex}`
+		}));
+		const extracted = yield* installer.extractTar(archive).pipe(Effect.mapError(fromInstaller(pin)));
+		const nativeName = windows ? "pnpm.exe" : "pnpm";
+		const native = path.join(extracted, "package", nativeName);
+		yield* assertFile(pin, native, `package/${nativeName} is missing from the ${packageName} tarball`);
+		const cacheError = (subject) => (cause) => errorFor(pin)({
+			reason: "cacheFailed",
+			subject,
+			cause
+		});
+		if (windows) {
+			for (const name of PNPM_NATIVE_BIN_NAMES) {
+				const relative = bins[name];
+				if (relative === void 0) continue;
+				for (const destination of [path.join(packageDir, relative), path.join(packageDir, `${relative}.exe`)]) yield* fs.copyFile(native, destination).pipe(Effect.mapError(cacheError(destination)));
+			}
+			return nativeWindowsBins(bins);
+		}
+		const destination = path.join(packageDir, placeholder);
+		yield* fs.copyFile(native, destination).pipe(Effect.mapError(cacheError(destination)));
+		for (const relative of Object.values(bins)) if (!isNodeScript(relative)) {
+			const file = path.join(packageDir, relative);
+			yield* fs.chmod(file, 493).pipe(Effect.mapError(cacheError(file)));
+		}
+		return bins;
 	});
 	/** Download bun's per-platform zip from GitHub releases and cache the binary. */
 	const installBun = (pin) => Effect.gen(function* () {
@@ -386,12 +540,12 @@ const make = Effect.gen(function* () {
 		if (!berry) yield* verifyIntegrity(pin, archive);
 		const extracted = yield* installer.extractTar(archive).pipe(Effect.mapError(fromInstaller(pin)));
 		const packageDir = path.join(extracted, "package");
-		const stat = yield* Effect.result(fs.stat(packageDir));
-		if (stat._tag !== "Success" || stat.success.type !== "Directory") return yield* Effect.fail(errorFor(pin)({
+		if ((yield* typeAt(fs, packageDir)) !== "Directory") return yield* Effect.fail(errorFor(pin)({
 			reason: "layoutUnexpected",
 			subject: "tarball has no package/ root"
 		}));
-		const bins = yield* readPackageBins(pin, packageDir);
+		const manifest = yield* readPackageManifest(pin, packageDir);
+		const bins = Object.keys(manifest.nativePackages).length > 0 ? yield* overlayNativeBinary(pin, packageDir, manifest.bins, manifest.nativePackages, registry) : manifest.bins;
 		if (berry) {
 			const cli = path.join(packageDir, "bin/yarn.js");
 			yield* assertFile(pin, cli, "bin/yarn.js is missing from the cli-dist tarball");
@@ -420,7 +574,10 @@ const make = Effect.gen(function* () {
 		});
 		if (options?.requireIntegrity === true && pin.integrity === void 0) return yield* Effect.fail(errorFor(pin)({ reason: "integrityMissing" }));
 		const cached = yield* installer.find(pin.name, version);
-		if (Option.isSome(cached)) return yield* cachedRecord(pin, cached.value);
+		if (Option.isSome(cached)) {
+			const record = yield* cachedRecord(pin, cached.value);
+			if (Option.isSome(record)) return record.value;
+		}
 		if (pin.name === "npm" && options?.allowAmbient !== false) {
 			const probed = yield* ambientNpmVersion;
 			if (Option.isSome(probed) && probed.value === version) return AmbientPackageManager.make({
@@ -437,9 +594,7 @@ const make = Effect.gen(function* () {
 		return yield* installFromRegistry(pin, pin.name, registry);
 	}) };
 });
-const unimplemented = (member) => {
-	throw new Error(`PackageManagerInstaller.makeTest: ${member}() was called but not stubbed — pass a \`${member}\` override.`);
-};
+const dies = unstubbed("PackageManagerInstaller.makeTest");
 /**
 * First-class exact-version package-manager provisioning on a GitHub runner.
 *
@@ -483,7 +638,7 @@ var PackageManagerInstaller = class PackageManagerInstaller extends Context.Serv
 	static layer = Layer.effect(this, make);
 	/** A test double. The unstubbed member dies rather than reporting an install that did not happen. */
 	static makeTest = (overrides = {}) => ({
-		install: () => Effect.sync(() => unimplemented("install")),
+		install: () => dies("install"),
 		...overrides
 	});
 	/** {@link PackageManagerInstaller.makeTest} behind `Layer.succeed`. */

package/ToolInstaller.js

@@ -1,4 +1,8 @@
 import { ActionEnvironment } from "./ActionEnvironment.js";
+import { unstubbed } from "./internal/unstubbed.js";
+import { isWindowsRunner, toolCacheRoot } from "./internal/runner.js";
+import { spawnOnce } from "./internal/spawn.js";
+import { typeAt } from "./internal/fsProbe.js";
 import { Context, Effect, FileSystem, Layer, Option, Path, Schedule, Schema, Stream } from "effect";
 import { HttpClient } from "effect/unstable/http";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
@@ -61,11 +65,8 @@ const make = Effect.gen(function* () {
 	const path = yield* Path.Path;
 	const http = yield* HttpClient.HttpClient;
 	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
-	const root = yield* Effect.map(env.getOptional("RUNNER_TOOL_CACHE"), (found) => Option.getOrElse(found, () => path.join("/tmp", "runner-tool-cache")));
-	const windows = yield* Effect.map(env.getOptional("RUNNER_OS"), (found) => Option.match(found, {
-		onNone: () => false,
-		onSome: (os) => os.toLowerCase() === "windows"
-	}));
+	const root = yield* toolCacheRoot(env, path);
+	const windows = yield* isWindowsRunner(env);
 	const cachePath = (tool, version) => ToolInstaller.cachePath({
 		root,
 		tool,
@@ -93,30 +94,22 @@ const make = Effect.gen(function* () {
 	* the difference between "this is not a gzip archive" and "tar is not
 	* installed". Discarding it is what makes an extraction failure unactionable.
 	*
-	* **One spawn, not two — load-bearing.** The spawner's convenience members
-	* each spawn independently: `string` collects output without inspecting the
-	* exit code, and `exitCode` runs the command AGAIN (core's
-	* `ChildProcessSpawner.make` derives both from `spawn`). Calling them
-	* back-to-back double-executed every extraction — harmless for idempotent
-	* `tar`/`unzip -o`, but .NET's `ZipFile.ExtractToDirectory` refuses to
-	* overwrite, so the second run failed 5/5 on real Windows runners while the
-	* captured "complaint" was the FIRST run's silent success. Output and exit
-	* code must come from the same `spawn` handle.
+	* **One spawn, not two — load-bearing**, and why is spelled once in
+	* `internal/spawn.ts`: the double run failed 5/5 on real Windows runners
+	* because .NET's `ZipFile.ExtractToDirectory` refuses to overwrite.
 	*/
-	const extractWith = (command, archive) => Effect.scoped(Effect.gen(function* () {
-		const extractError = (cause) => new ToolInstallerError({
+	const extractWith = (command, archive) => Effect.gen(function* () {
+		const { output, code } = yield* spawnOnce(spawner, command).pipe(Effect.mapError((cause) => new ToolInstallerError({
 			reason: "extractFailed",
 			subject: archive,
 			cause
-		});
-		const handle = yield* spawner.spawn(command).pipe(Effect.mapError(extractError));
-		const output = yield* Stream.mkString(Stream.decodeText(handle.all)).pipe(Effect.mapError(extractError));
-		if ((yield* handle.exitCode.pipe(Effect.mapError(extractError))) !== 0) return yield* Effect.fail(new ToolInstallerError({
+		})));
+		if (code !== 0) return yield* Effect.fail(new ToolInstallerError({
 			reason: "extractFailed",
 			subject: archive,
 			stderr: output.trim()
 		}));
-	}));
+	});
 	/**
 	* Install a staged directory into the tool cache by renaming it into place.
 	*
@@ -191,7 +184,7 @@ const make = Effect.gen(function* () {
 			while: (error) => error.retryable
 		}));
 	});
-	const find = (tool, version) => Effect.map(Effect.result(fs.stat(cachePath(tool, version))), (result) => result._tag === "Success" && result.success.type === "Directory" ? Option.some(cachePath(tool, version)) : Option.none());
+	const find = (tool, version) => Effect.map(typeAt(fs, cachePath(tool, version)), (type) => type === "Directory" ? Option.some(cachePath(tool, version)) : Option.none());
 	const cacheFile = Effect.fn("ToolInstaller.cacheFile")(function* (source, name, tool, version) {
 		yield* Effect.annotateCurrentSpan({
 			tool,
@@ -252,8 +245,7 @@ const make = Effect.gen(function* () {
 			});
 			const cached = yield* find(options.tool, options.version);
 			if (Option.isSome(cached)) {
-				const present = yield* Effect.result(fs.stat(path.join(cached.value, options.binary)));
-				if (present._tag === "Success" && present.success.type === "File") return {
+				if ((yield* typeAt(fs, path.join(cached.value, options.binary))) === "File") return {
 					directory: cached.value,
 					binDir: cached.value
 				};
@@ -272,9 +264,7 @@ const make = Effect.gen(function* () {
 		})
 	};
 });
-const unimplemented = (member) => {
-	throw new Error(`ToolInstaller.makeTest: ${member}() was called but not stubbed — pass a \`${member}\` override.`);
-};
+const dies = unstubbed("ToolInstaller.makeTest");
 /**
 * Download, extract and cache a toolchain in the runner's tool cache.
 *
@@ -323,13 +313,13 @@ var ToolInstaller = class ToolInstaller extends Context.Service()("@effected/git
 	static cachePath = (options) => `${options.root}/${options.tool}/${options.version}/${options.arch}`;
 	/** A test double. Unstubbed members die rather than reporting a tool that is not there. */
 	static makeTest = (overrides = {}) => ({
-		find: () => Effect.sync(() => unimplemented("find")),
-		download: () => Effect.sync(() => unimplemented("download")),
-		extractTar: () => Effect.sync(() => unimplemented("extractTar")),
-		extractZip: () => Effect.sync(() => unimplemented("extractZip")),
-		cacheDir: () => Effect.sync(() => unimplemented("cacheDir")),
-		cacheFile: () => Effect.sync(() => unimplemented("cacheFile")),
-		provisionFile: () => Effect.sync(() => unimplemented("provisionFile")),
+		find: () => dies("find"),
+		download: () => dies("download"),
+		extractTar: () => dies("extractTar"),
+		extractZip: () => dies("extractZip"),
+		cacheDir: () => dies("cacheDir"),
+		cacheFile: () => dies("cacheFile"),
+		provisionFile: () => dies("provisionFile"),
 		...overrides
 	});
 	/** {@link ToolInstaller.makeTest} behind `Layer.succeed`. */