fallow 3.16.0 → 3.18.0

package/README.md

@@ -28,7 +28,7 @@ npx fallow fix --dry-run         # Preview automatic cleanup
 
 ## Output and exit codes
 
-Add `--format json --quiet` to any command for one typed JSON document on stdout. Exit code 1 means findings, not failure; 0 is clean (or an audit pass or warn verdict); 2 is a validation or runtime error, reported as a JSON error envelope rather than a stack trace.
+Add `--format json --quiet` to any command for one typed JSON document on stdout. Exit code 1 means findings, not failure; 0 is clean (or an audit pass or warn verdict); 2 is a validation or runtime error, reported as a JSON error envelope rather than a stack trace. License, coverage setup, network, and security-gate workflows use additional documented codes; read `fallow schema.exit_codes` instead of suppressing the process status.
 
 Parsing the output in TypeScript? Import the typed shapes, version-pinned to the CLI you install:
 

package/capabilities.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "3.16.0",
+  "version": "3.18.0",
   "manifest_version": "1",
   "description": "Codebase analyzer for TypeScript/JavaScript: unused code, circular dependencies, code duplication, complexity hotspots, and architecture boundary violations",
   "global_flags": [
@@ -302,7 +302,7 @@
       "name": "--report-path-prefix",
       "type": "string",
       "required": false,
-      "description": "Prefix prepended to every path in the CI-facing formats (`github-annotations`, `github-summary`, `codeclimate`, `review-github`, `review-gitlab`). CI platforms address files by repository-root-relative path, so when the analyzed project lives in a subdirectory (e.g. `packages/app/`), paths need that offset. fallow detects the offset via the git toplevel automatically; this flag overrides the detection. Pass an empty string to disable rebasing and emit paths relative to `--root`"
+      "description": "Prefix prepended to every path in the CI-facing formats (`github-annotations`, `github-summary`, `codeclimate`, `pr-comment-github`, `pr-comment-gitlab`, `review-github`, `review-gitlab`). CI platforms address files by repository-root-relative path, so when the analyzed project lives in a subdirectory (e.g. `packages/app/`), paths need that offset. fallow detects the offset via the git toplevel automatically; this flag overrides the detection. Pass an empty string to disable rebasing and emit paths relative to `--root`"
     },
     {
       "name": "--fail-on-regression",
@@ -815,7 +815,7 @@
           "name": "--unused-dependency-overrides",
           "type": "bool",
           "required": false,
-          "description": "Only report unused pnpm dependency overrides",
+          "description": "Only report unused package-manager dependency overrides",
           "possible_values": [
             "true",
             "false"
@@ -825,7 +825,7 @@
           "name": "--misconfigured-dependency-overrides",
           "type": "bool",
           "required": false,
-          "description": "Only report misconfigured pnpm dependency overrides",
+          "description": "Only report misconfigured package-manager dependency overrides",
           "possible_values": [
             "true",
             "false"
@@ -1659,13 +1659,13 @@
           "name": "--coverage",
           "type": "string",
           "required": false,
-          "description": "Path to Istanbul-format coverage data (coverage-final.json) for accurate per-function CRAP scores in the health sub-analysis. Also configurable via FALLOW_COVERAGE"
+          "description": "Path to Istanbul-format coverage data (coverage-final.json) for accurate per-function CRAP scores in the health sub-analysis. Also configurable via FALLOW_COVERAGE or health.coverage"
         },
         {
           "name": "--coverage-root",
           "type": "string",
           "required": false,
-          "description": "Absolute prefix to strip from coverage data paths before CRAP matching. Use when coverage was generated under a different checkout root in CI or Docker"
+          "description": "Absolute prefix to strip from coverage data paths before CRAP matching. Use when coverage was generated under a different checkout root in CI or Docker. Also configurable via FALLOW_COVERAGE_ROOT or health.coverageRoot"
         },
         {
           "name": "--no-css",
@@ -1897,7 +1897,7 @@
     },
     {
       "name": "report",
-      "description": "Render a saved `--format json` results file in another format without re-running analysis (analyze once, render annotations and the job summary from the same file). Supports `github-annotations`, `github-summary`, `codeclimate`, and `sarif`",
+      "description": "Render a saved `--format json` results file in another format without re-running analysis (analyze once, then render every CI surface from the same file). Supports GitHub annotations/summary, CodeClimate, SARIF, and GitHub/GitLab PR-comment and review formats",
       "flags": [
         {
           "name": "--from",
@@ -3094,7 +3094,7 @@
       "rule_id": "fallow/unused-dependency-override",
       "command": "dead-code",
       "category": "Dependencies",
-      "description": "pnpm.overrides entry targets a package not declared or resolved",
+      "description": "Package-manager override target is not declared or resolved",
       "label": "Unused Dependency Overrides",
       "config_key": "unused-dependency-overrides",
       "registry_index": 42,
@@ -3135,7 +3135,7 @@
       "rule_id": "fallow/misconfigured-dependency-override",
       "command": "dead-code",
       "category": "Dependencies",
-      "description": "pnpm.overrides entry has an unparsable key or value",
+      "description": "Package-manager override has an unparsable key or value",
       "label": "Misconfigured Dependency Overrides",
       "config_key": "misconfigured-dependency-overrides",
       "registry_index": 43,
@@ -5923,18 +5923,32 @@
     "sarif",
     "compact",
     "markdown",
+    "md",
     "codeclimate",
     "gitlab-codequality",
+    "gitlab-code-quality",
     "pr-comment-github",
     "pr-comment-gitlab",
     "review-github",
     "review-gitlab",
-    "badge"
+    "badge",
+    "github-annotations",
+    "github-summary"
   ],
   "exit_codes": {
     "0": "Success (no error-severity issues found)",
-    "1": "Error-severity issues found (per rules config, or --fail-on-issues promotes warn→error)",
-    "2": "Error (invalid config, invalid input, etc.). When --format json is active, errors are emitted as structured JSON on stdout: {\"error\": true, \"message\": \"...\", \"exit_code\": 2}"
+    "1": "Error-severity issues found (per rules config, or --fail-on-issues promotes warn to error)",
+    "2": "Error (invalid config, invalid input, etc.). When --format json is active, errors are emitted as structured JSON on stdout: {\"error\": true, \"message\": \"...\", \"exit_code\": 2}",
+    "3": "Requested resource unavailable: config --path found no config, or a license is missing, invalid, or beyond its offline hard-fail window",
+    "4": "Runtime coverage sidecar is unavailable, unverifiable, protocol-incompatible, or terminated unexpectedly",
+    "5": "Runtime coverage input could not be prepared or parsed",
+    "6": "Runtime coverage sidecar reported an internal error",
+    "7": "Network or cloud request failed during a license, coverage, or CI operation",
+    "8": "Security gate matched a candidate selected by --gate",
+    "10": "Coverage inventory or static-findings upload input or project validation failed",
+    "11": "Coverage inventory or static-findings upload exceeded the server payload limit",
+    "12": "Coverage inventory or static-findings upload authentication or authorization was rejected",
+    "13": "Coverage inventory or static-findings upload failed after retries or returned another server error"
   },
   "environment_variables": {
     "FALLOW_FORMAT": "Default output format (json/human/sarif/compact/markdown/codeclimate/gitlab-codequality/pr-comment-github/pr-comment-gitlab/review-github/review-gitlab/badge/github-annotations/github-summary). CLI --format flag overrides this.",
@@ -5949,14 +5963,14 @@
     "FALLOW_PR_COMMENT_LAYOUT": "Sticky PR comment layout: default, compact, gate-only, or details.",
     "FALLOW_CONSOLIDATED_STATUS": "When split PR gate check runs are enabled, truthy values add one aggregate Fallow check alongside the per-gate checks.",
     "FALLOW_DIFF_CONTEXT": "Line radius around changed diff lines when scoping findings to a diff in the review/PR-comment formats (default 3).",
-    "FALLOW_BOT_LOGIN": "Bot or token username treated as fallow's own when reconciling existing PR/MR comments in review-github/review-gitlab. Required when posting with a personal access token (the author then carries a human identity).",
+    "FALLOW_BOT_LOGIN": "Allowlisted posting username used to recognize fallow-owned finding roots and resolution replies. When set, it narrows ownership to that exact username (an empty value matches nobody); when unset, provider-native bot metadata is trusted. This is an authorship control, not a lifecycle or deduplication token.",
     "FALLOW_API_RETRIES": "Maximum HTTP attempts for review-comment reconciliation API calls (default 3).",
     "FALLOW_API_RETRY_DELAY": "Floor delay in seconds between HTTP retry attempts (default 2); a server-supplied Retry-After overrides it on 429 responses.",
     "FALLOW_CACHE_DIR": "Directory for fallow's persistent analysis cache. Relative paths resolve from the project root and override cache.dir.",
     "FALLOW_CACHE_MAX_SIZE": "Extraction cache size cap in megabytes (default 256). Wins over the cache.maxSizeMb config field.",
     "FALLOW_EXTENDS_TIMEOUT_SECS": "Timeout in seconds for fetching https:// configs referenced via the extends field (default 5).",
-    "FALLOW_COVERAGE": "Path to Istanbul coverage data (coverage-final.json) for accurate per-function CRAP scores. CLI --coverage flag overrides this.",
-    "FALLOW_COVERAGE_ROOT": "Absolute coverage-data path prefix for rebasing Istanbul paths in CI or containers. CLI --coverage-root flag overrides this.",
+    "FALLOW_COVERAGE": "Path to Istanbul coverage data (coverage-final.json) for accurate per-function CRAP scores. CLI --coverage flag overrides this; it wins over the health.coverage config field. Honored by the health, bare fallow, and audit CLI commands and by the MCP audit and check_health tools on both their typed route and their CLI fallback, where the explicit coverage parameter overrides it.",
+    "FALLOW_COVERAGE_ROOT": "Absolute coverage-data path prefix for rebasing Istanbul paths in CI or containers. CLI --coverage-root flag overrides this; it wins over the health.coverageRoot config field. Honored by the health, bare fallow, and audit CLI commands and by the MCP audit and check_health tools on both their typed route and their CLI fallback, where the explicit coverage_root parameter overrides it.",
     "FALLOW_MAX_FILE_SIZE": "Per-file size ceiling in megabytes for source discovery (default 5; 0 = no limit). CLI --max-file-size flag overrides this.",
     "FALLOW_TYPE_AWARE": "Enable or disable TypeScript semantic (type-aware) analysis for the run (true/false/1/0/yes/no/on/off). Precedence: --type-aware/--no-type-aware CLI flags, then FALLOW_TYPE_AWARE, then the audit.typeAware config field, then typeAware.enabled.",
     "FALLOW_TYPE_AWARE_BIN": "Trusted executable override for the TypeScript semantic refinement sidecar used by dead-code --type-aware. Relative paths resolve from the caller's working directory before --root is applied; project node_modules and PATH are intentionally not searched. Default: sibling of the active Fallow executable.",
@@ -6837,7 +6851,7 @@
       {
         "name": "trace_symbol",
         "kind": "trace",
-        "description": "Trace an exact TypeScript symbol with checker-backed references, namespace identity, aliases, and re-export hops. Root trace fields preserve syntactic context; treat semantic.references, semantic.status, and semantic.identity as the authoritative exact evidence. This is project-wide evidence for Fallow decisions, not a compiler-diagnostic or lint-rule surface.",
+        "description": "Trace an exact TypeScript symbol with checker-backed references, namespace identity, aliases, and re-export hops. Root trace fields preserve syntactic context; treat semantic.references, semantic.status, and semantic.identity as the authoritative exact evidence. The proof covers only the lane named by semantic.target.namespace, so a root trace that lists a reference the proof does not is wider evidence rather than stale. This is project-wide evidence for Fallow decisions, not a compiler-diagnostic or lint-rule surface.",
         "cli_command": "fallow dead-code --type-aware --trace <file:export> --format json --quiet",
         "key_params": [
           "file",

package/issue-registry.json

@@ -1558,7 +1558,7 @@
       "rule_id": "fallow/unused-dependency-override",
       "command": "dead-code",
       "category": "Dependencies",
-      "description": "pnpm.overrides entry targets a package not declared or resolved",
+      "description": "Package-manager override target is not declared or resolved",
       "label": "Unused Dependency Overrides",
       "config_key": "unused-dependency-overrides",
       "registry_index": 42,
@@ -1599,7 +1599,7 @@
       "rule_id": "fallow/misconfigured-dependency-override",
       "command": "dead-code",
       "category": "Dependencies",
-      "description": "pnpm.overrides entry has an unparsable key or value",
+      "description": "Package-manager override has an unparsable key or value",
       "label": "Misconfigured Dependency Overrides",
       "config_key": "misconfigured-dependency-overrides",
       "registry_index": 43,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "3.16.0",
+  "version": "3.18.0",
   "description": "Codebase intelligence for TypeScript and JavaScript. Free static analysis of code and styles, optional paid runtime intelligence (Fallow Runtime). Quality, risk, architecture, dependencies, duplication, and design-system drift for humans, CI, and the agents writing your code. Zero-config framework support.",
   "license": "MIT",
   "repository": {
@@ -87,14 +87,14 @@
     "@tanstack/intent": "0.3.6"
   },
   "optionalDependencies": {
-    "@fallow-cli/darwin-arm64": "3.16.0",
-    "@fallow-cli/darwin-x64": "3.16.0",
-    "@fallow-cli/linux-x64-gnu": "3.16.0",
-    "@fallow-cli/linux-arm64-gnu": "3.16.0",
-    "@fallow-cli/linux-x64-musl": "3.16.0",
-    "@fallow-cli/linux-arm64-musl": "3.16.0",
-    "@fallow-cli/win32-arm64-msvc": "3.16.0",
-    "@fallow-cli/win32-x64-msvc": "3.16.0",
-    "fallow-type-aware": "3.16.0"
+    "@fallow-cli/darwin-arm64": "3.18.0",
+    "@fallow-cli/darwin-x64": "3.18.0",
+    "@fallow-cli/linux-x64-gnu": "3.18.0",
+    "@fallow-cli/linux-arm64-gnu": "3.18.0",
+    "@fallow-cli/linux-x64-musl": "3.18.0",
+    "@fallow-cli/linux-arm64-musl": "3.18.0",
+    "@fallow-cli/win32-arm64-msvc": "3.18.0",
+    "@fallow-cli/win32-x64-msvc": "3.18.0",
+    "fallow-type-aware": "3.18.0"
   }
 }

package/schema.json

@@ -1028,7 +1028,7 @@
           "default": 60
         },
         "coverage": {
-          "description": "Path to Istanbul-format coverage data for accurate per-function CRAP\nscores. Relative paths resolve against the project root. The CLI\n`--coverage` flag and `FALLOW_COVERAGE` environment variable override\nthis value.",
+          "description": "Path to Istanbul-format coverage data for accurate per-function CRAP\nscores. Relative paths resolve against the project root. The CLI\n`--coverage` flag and `FALLOW_COVERAGE` environment variable override\nthis value. Consulted by `fallow health`, bare `fallow`, `fallow audit`,\nand the MCP `audit` / `check_health` tools.",
           "type": [
             "string",
             "null"
@@ -1036,7 +1036,7 @@
           "default": null
         },
         "coverageRoot": {
-          "description": "Absolute prefix to strip from Istanbul file paths before CRAP matching.\nUse when coverage was generated under a different checkout root in CI\nor Docker. The CLI `--coverage-root` flag and `FALLOW_COVERAGE_ROOT`\nenvironment variable override this value.",
+          "description": "Absolute prefix to strip from Istanbul file paths before CRAP matching.\nUse when coverage was generated under a different checkout root in CI\nor Docker. The CLI `--coverage-root` flag and `FALLOW_COVERAGE_ROOT`\nenvironment variable override this value. Consulted by `fallow health`,\nbare `fallow`, `fallow audit`, and the MCP `audit` / `check_health`\ntools.",
           "type": [
             "string",
             "null"
@@ -1458,12 +1458,12 @@
           "default": "error"
         },
         "unused-dependency-overrides": {
-          "description": "A pnpm `overrides:` / `pnpm.overrides` entry whose target package no\nworkspace `package.json` declares. Defaults to `warn`.",
+          "description": "A pnpm, npm, or Bun override entry whose target package no workspace\n`package.json` declares and the active readable lockfile does not\nresolve. Defaults to `warn`.",
           "$ref": "#/$defs/Severity",
           "default": "warn"
         },
         "misconfigured-dependency-overrides": {
-          "description": "A pnpm `overrides:` / `pnpm.overrides` entry whose key or value cannot\nbe parsed into a valid pnpm shape. Defaults to `error`.",
+          "description": "A pnpm, npm, or Bun override or Bun `resolutions` entry whose key or\nvalue cannot be parsed in its declaration source's grammar. Defaults to\n`error`.",
           "$ref": "#/$defs/Severity",
           "default": "error"
         },

package/scripts/lazy-verify.js

@@ -235,6 +235,9 @@ function isSkipRequested(env) {
 //                    production install path always has fallowDigests)
 //   env            - process.env (defaults to process.env)
 //   platform       - process.platform (defaults to process.platform)
+//   homedir        - os.homedir() override (tests only)
+//   isWritable     - sentinel directory probe override (tests only)
+//   ensureDir      - sentinel directory creation override (tests only)
 //   logger         - function (line: string) -> void (defaults to stderr)
 //
 // Returns one of:
@@ -253,6 +256,16 @@ function buildVerifyOptions(input, manifest) {
   return opts;
 }
 
+function buildSentinelOptions(input, platformPkgDir, packageName, env, platform) {
+  const opts = { platformPkgDir, packageName, env, platform };
+  for (const key of ["homedir", "isWritable", "ensureDir"]) {
+    if (Object.prototype.hasOwnProperty.call(input, key)) {
+      opts[key] = input[key];
+    }
+  }
+  return opts;
+}
+
 // Persist the sentinel on a successful verify. Logs (warn-once) when the
 // resolved cache location is read-only or every cascade step failed.
 function persistSentinel(sentinel, platformPkgDir, manifest, platform) {
@@ -315,7 +328,9 @@ function ensureVerified(input) {
     };
   }
 
-  const sentinel = resolveSentinelPath({ platformPkgDir, packageName, env, platform });
+  const sentinel = resolveSentinelPath(
+    buildSentinelOptions(input || {}, platformPkgDir, packageName, env, platform),
+  );
 
   // Cache hit: sentinel exists, schema matches, mtimes match, version matches.
   if (sentinel.path && isSentinelValid(sentinel.path, platformPkgDir, manifest, platform)) {

package/scripts/lazy-verify.test.js

@@ -16,6 +16,9 @@ const { _verifyWithKey, SKIP_ENV } = require("./verify-binary");
 
 // ---- shared fixtures ------------------------------------------------------
 
+const DEFAULT_PLATFORM = "linux";
+const DEFAULT_PACKAGE_NAME = "@fallow-cli/test-platform";
+
 function makeKeypair() {
   const { privateKey, publicKey } = crypto.generateKeyPairSync("ed25519");
   const spki = publicKey.export({ format: "der", type: "spki" });
@@ -23,18 +26,18 @@ function makeKeypair() {
   return { privateKey, rawPub };
 }
 
-function ext() {
-  return process.platform === "win32" ? ".exe" : "";
+function packageNameForPlatform(platform) {
+  return platform === "win32" ? "@fallow-cli/win32-x64-msvc" : DEFAULT_PACKAGE_NAME;
 }
 
-function binaryNames() {
+function binaryNames(platform) {
   // Platform packages ship a single multicall `fallow` binary.
-  return [`fallow${ext()}`];
+  return [platform === "win32" ? "fallow.exe" : "fallow"];
 }
 
-function computeDigestsForDir(dir) {
+function computeDigestsForDir(dir, platform) {
   const out = {};
-  for (const base of binaryNames()) {
+  for (const base of binaryNames(platform)) {
     const full = path.join(dir, base);
     out[base] = "sha256:" + crypto.createHash("sha256").update(fs.readFileSync(full)).digest("hex");
   }
@@ -43,8 +46,9 @@ function computeDigestsForDir(dir) {
 
 function mkPlatformDir(privateKey, options) {
   const opts = options || {};
+  const platform = opts.platform || DEFAULT_PLATFORM;
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), "fallow-lazy-test-"));
-  for (const base of binaryNames()) {
+  for (const base of binaryNames(platform)) {
     const binaryPath = path.join(dir, base);
     const content = Buffer.from(`mock ${base}`);
     fs.writeFileSync(binaryPath, content);
@@ -56,9 +60,9 @@ function mkPlatformDir(privateKey, options) {
   fs.writeFileSync(
     path.join(dir, "package.json"),
     JSON.stringify({
-      name: opts.packageName || "@fallow-cli/test-platform",
+      name: opts.packageName || packageNameForPlatform(platform),
       version: opts.version || "2.81.0",
-      fallowDigests: opts.skipDigests ? undefined : computeDigestsForDir(dir),
+      fallowDigests: opts.skipDigests ? undefined : computeDigestsForDir(dir, platform),
     }),
   );
   return dir;
@@ -88,13 +92,15 @@ function setupCacheRoot(t) {
 }
 
 function baseInput(dir, verifyFn, extras) {
+  const manifestPath = path.join(dir, "package.json");
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
   return {
     platformPkgDir: dir,
-    packageName: "@fallow-cli/test-platform",
-    manifestPath: path.join(dir, "package.json"),
+    packageName: manifest.name,
+    manifestPath,
     verifyFn,
     env: {},
-    platform: process.platform,
+    platform: DEFAULT_PLATFORM,
     ...extras,
   };
 }
@@ -120,6 +126,29 @@ test("ensureVerified verifies on cache miss and writes the sentinel", (t) => {
   assert.equal(Object.keys(sentinel.binaries).length, 1);
 });
 
+test("ensureVerified verifies and caches a win32 executable on any host", (t) => {
+  _resetWarningState();
+  const { privateKey, rawPub } = makeKeypair();
+  const dir = mkPlatformDir(privateKey, { platform: "win32" });
+  t.after(() => cleanup(dir));
+  const input = baseInput(dir, (binaryPath) => _verifyWithKey(binaryPath, rawPub), {
+    platform: "win32",
+  });
+
+  const verified = ensureVerified(input);
+  assert.equal(verified.ok, true);
+  assert.equal(verified.cached, false);
+  const sentinel = JSON.parse(fs.readFileSync(verified.sentinelPath, "utf8"));
+  assert.deepEqual(Object.keys(sentinel.binaries), ["fallow.exe"]);
+
+  const cached = ensureVerified({
+    ...input,
+    verifyFn: () => assert.fail("signature verification must not run on a cache hit"),
+  });
+  assert.equal(cached.ok, true);
+  assert.equal(cached.cached, true);
+});
+
 test("ensureVerified returns cached:true on a valid sentinel", (t) => {
   _resetWarningState();
   const { privateKey, rawPub } = makeKeypair();
@@ -154,7 +183,7 @@ test("ensureVerified invalidates sentinel on mtime drift", (t) => {
 
   // Bump the mtime of one binary; sentinel should now be stale.
   const newTime = new Date(Date.now() + 10_000);
-  fs.utimesSync(path.join(dir, `fallow${ext()}`), newTime, newTime);
+  fs.utimesSync(path.join(dir, binaryNames(DEFAULT_PLATFORM)[0]), newTime, newTime);
 
   let verifyCallCount = 0;
   const result = ensureVerified(
@@ -215,7 +244,9 @@ test("ensureVerified invalidates sentinel on packageName drift", (t) => {
       packageVersion: "2.81.0",
       packageName: "@fallow-cli/wrong-name",
       binaries: {
-        [`fallow${ext()}`]: { mtimeMs: fs.statSync(path.join(dir, `fallow${ext()}`)).mtimeMs },
+        [binaryNames(DEFAULT_PLATFORM)[0]]: {
+          mtimeMs: fs.statSync(path.join(dir, binaryNames(DEFAULT_PLATFORM)[0])).mtimeMs,
+        },
       },
     }),
   );
@@ -261,7 +292,7 @@ test("ensureVerified invalidates sentinel on schemaVersion drift", (t) => {
 test("ensureVerified returns sig-invalid on a tampered signature", (t) => {
   _resetWarningState();
   const { privateKey, rawPub } = makeKeypair();
-  const dir = mkPlatformDir(privateKey, { corruptSigFor: `fallow${ext()}` });
+  const dir = mkPlatformDir(privateKey, { corruptSigFor: binaryNames(DEFAULT_PLATFORM)[0] });
   t.after(() => cleanup(dir));
 
   const result = ensureVerified(baseInput(dir, (p) => _verifyWithKey(p, rawPub)));
@@ -289,89 +320,43 @@ test("ensureVerified returns digest-unavailable on a pre-#597 manifest", (t) =>
 
 test("ensureVerified honors FALLOW_VERIFY_CACHE_DIR when platform pkg dir is non-writable", (t) => {
   _resetWarningState();
-  if (process.platform === "win32") {
-    t.skip("Windows ACL chmod is not portable; covered by sentinel-path tests");
-    return;
-  }
   const { privateKey, rawPub } = makeKeypair();
   const dir = mkPlatformDir(privateKey);
   const cacheRoot = setupCacheRoot(t);
+  t.after(() => cleanup(dir));
 
-  fs.chmodSync(dir, 0o555);
-  try {
-    const result = ensureVerified({
-      ...baseInput(dir, (p) => _verifyWithKey(p, rawPub)),
-      env: { FALLOW_VERIFY_CACHE_DIR: cacheRoot },
-    });
-    assert.equal(result.ok, true);
-    assert.equal(result.cached, false);
-    assert.match(result.sentinelPath, new RegExp(cacheRoot.replace(/\\/g, "\\\\")));
-  } finally {
-    fs.chmodSync(dir, 0o755);
-    cleanup(dir);
-  }
+  const result = ensureVerified({
+    ...baseInput(dir, (p) => _verifyWithKey(p, rawPub)),
+    env: { FALLOW_VERIFY_CACHE_DIR: cacheRoot },
+    isWritable: (candidate) => candidate !== dir,
+  });
+  assert.equal(result.ok, true);
+  assert.equal(result.cached, false);
+  assert.match(result.sentinelPath, new RegExp(cacheRoot.replace(/\\/g, "\\\\")));
 });
 
-test("ensureVerified emits a single warning when sentinel write fails", (t) => {
+test("ensureVerified emits a single warning when no sentinel location is writable", (t) => {
   _resetWarningState();
-  if (process.platform === "win32") {
-    t.skip("Windows ACL chmod is not portable");
-    return;
-  }
   const { privateKey, rawPub } = makeKeypair();
   const dir = mkPlatformDir(privateKey);
   const stderr = captureStderr(t);
+  t.after(() => cleanup(dir));
+  const input = {
+    ...baseInput(dir, (p) => _verifyWithKey(p, rawPub)),
+    homedir: undefined,
+    isWritable: () => false,
+  };
 
-  // Make platform pkg dir non-writable AND point FALLOW_VERIFY_CACHE_DIR at
-  // a non-existent path. resolveSentinelPath will still find the XDG / home
-  // fallback, but we can simulate "every cache location read-only" by giving
-  // it a writable dir that we then chmod down right before ensureVerified
-  // runs writeSentinel. Simpler: instead of fighting the cascade in env,
-  // simulate write failure via a non-writable FALLOW_VERIFY_CACHE_DIR that
-  // PASSES isWritable() but then has its perms revoked between resolve and
-  // write. Since that race is hard to script, we test the warn-once helper
-  // via a synthetic path that fails the rename atomically: pass a sentinel-
-  // chmod-locked dir.
-  //
-  // The portable shape: chmod the platform pkg dir read-only AND pass a
-  // FALLOW_VERIFY_CACHE_DIR that is a regular file (not a dir). isWritable
-  // returns false for both, so resolveSentinelPath falls through to XDG. If
-  // the user has no HOME (synthetic env), the cascade returns null. We can
-  // achieve this only by injecting both env.HOME='' AND env.XDG_CACHE_HOME=''
-  // AND ensuring os.homedir() is not consulted; ensureVerified does not
-  // accept a homedir override, so the warn-once path is unreachable via env
-  // alone on a machine with a real HOME. Skip this test on machines with a
-  // real homedir; the warn-once helper is otherwise covered by the
-  // "no-writable-location" branch in sentinel-path tests.
-  if (os.homedir() && os.homedir().length > 0) {
-    t.skip(
-      "warn-once-on-no-writable-cache requires homedir-override knob (covered by sentinel-path unit test)",
-    );
-    cleanup(dir);
-    return;
-  }
+  const result = ensureVerified(input);
+  assert.equal(result.sentinelPath, null);
+  const warnings = stderr.lines.filter((line) => line.includes("no writable cache location"));
+  assert.equal(warnings.length, 1);
 
-  fs.chmodSync(dir, 0o555);
-  try {
-    const env = { HOME: "", XDG_CACHE_HOME: "" };
-    const result = ensureVerified({
-      ...baseInput(dir, (p) => _verifyWithKey(p, rawPub)),
-      env,
-    });
-    if (result.sentinelPath !== null) {
-      t.diagnostic(`sentinel landed at ${result.sentinelPath} despite empty HOME; skipping`);
-      return;
-    }
-    const warnings = stderr.lines.filter((l) => l.includes("no writable cache location"));
-    assert.equal(warnings.length, 1);
-    // Second call: no new warning.
-    ensureVerified({ ...baseInput(dir, (p) => _verifyWithKey(p, rawPub)), env });
-    const warnings2 = stderr.lines.filter((l) => l.includes("no writable cache location"));
-    assert.equal(warnings2.length, 1);
-  } finally {
-    fs.chmodSync(dir, 0o755);
-    cleanup(dir);
-  }
+  ensureVerified(input);
+  const repeatedWarnings = stderr.lines.filter((line) =>
+    line.includes("no writable cache location"),
+  );
+  assert.equal(repeatedWarnings.length, 1);
 });
 
 // ---- FALLOW_SKIP_BINARY_VERIFY -------------------------------------------
@@ -457,10 +442,6 @@ test("ensureVerified is idempotent under concurrent first-runs", async (t) => {
 
 test("ensureVerified rejects a sentinel written for a different install dir", (t) => {
   _resetWarningState();
-  if (process.platform === "win32") {
-    t.skip("chmod-based read-only platform pkg dir is not portable on Windows");
-    return;
-  }
   // Two installs of the same package + version. install A is clean and writes
   // a sentinel to a shared cache; install B has a tampered binary at the same
   // package name + version. B must NOT trust A's sentinel via cache hit even
@@ -471,17 +452,14 @@ test("ensureVerified rejects a sentinel written for a different install dir", (t
   // Tamper install B's fallow binary AFTER mkPlatformDir wrote a valid sig
   // for the original bytes (mkPlatformDir does not expose a corrupt-binary
   // option, so simulate the attack by overwriting bytes here).
-  fs.writeFileSync(path.join(installB, `fallow${ext()}`), Buffer.from("tampered bytes"));
+  fs.writeFileSync(
+    path.join(installB, binaryNames(DEFAULT_PLATFORM)[0]),
+    Buffer.from("tampered bytes"),
+  );
   const sharedCache = fs.mkdtempSync(path.join(os.tmpdir(), "fallow-shared-cache-"));
+  const isWritable = (candidate) => candidate !== installA && candidate !== installB;
 
-  // Force the shared-cache cascade by making both platform pkg dirs
-  // non-writable (simulates yarn PnP / Docker layered images / pnpm
-  // verify-store invariants).
-  fs.chmodSync(installA, 0o555);
-  fs.chmodSync(installB, 0o555);
   t.after(() => {
-    fs.chmodSync(installA, 0o755);
-    fs.chmodSync(installB, 0o755);
     cleanup(installA);
     cleanup(installB);
     cleanup(sharedCache);
@@ -492,6 +470,7 @@ test("ensureVerified rejects a sentinel written for a different install dir", (t
   const resultA = ensureVerified({
     ...baseInput(installA, (p) => _verifyWithKey(p, rawPub)),
     env: { FALLOW_VERIFY_CACHE_DIR: sharedCache },
+    isWritable,
   });
   assert.equal(resultA.ok, true);
   assert.match(resultA.sentinelPath, new RegExp(sharedCache.replace(/\\/g, "\\\\")));
@@ -502,7 +481,6 @@ test("ensureVerified rejects a sentinel written for a different install dir", (t
   // + SHA-256 binding must prevent that.
   for (const name of binaryNames()) {
     const aStat = fs.statSync(path.join(installA, name));
-    fs.chmodSync(path.join(installB, name), 0o644);
     fs.utimesSync(path.join(installB, name), aStat.atime, aStat.mtime);
   }
 
@@ -513,6 +491,7 @@ test("ensureVerified rejects a sentinel written for a different install dir", (t
       return _verifyWithKey(p, rawPub);
     }),
     env: { FALLOW_VERIFY_CACHE_DIR: sharedCache },
+    isWritable,
   });
   assert.equal(resultB.ok, false);
   assert.equal(resultB.code, "sig-invalid");
@@ -530,7 +509,7 @@ test("ensureVerified rejects a sentinel where bytes drift but mtime stays", (t)
 
   // Tamper the binary in place AND restore the prior mtime, so the mtime
   // pre-filter matches but the bytes do not.
-  const binPath = path.join(dir, `fallow${ext()}`);
+  const binPath = path.join(dir, binaryNames(DEFAULT_PLATFORM)[0]);
   const before = fs.statSync(binPath);
   fs.writeFileSync(binPath, Buffer.from("tampered"));
   fs.utimesSync(binPath, before.atime, before.mtime);

package/scripts/run-binary.js

@@ -145,18 +145,38 @@ function resolveTypeAwareCompanion(
   }
 }
 
-function childEnvironment(resolvedVersion, resolveCompanion = resolveTypeAwareCompanion) {
+function typeAwareCommand(
+  companion,
+  { platform = process.platform, execPath = process.execPath } = {},
+) {
+  return platform === "win32"
+    ? { binary: execPath, script: companion }
+    : { binary: companion, script: undefined };
+}
+
+function childEnvironment(
+  resolvedVersion,
+  resolveCompanion = resolveTypeAwareCompanion,
+  commandOptions,
+) {
   if (process.env.FALLOW_TYPE_AWARE_BIN) return process.env;
   const companion = resolveCompanion(resolvedVersion);
-  return companion === undefined
-    ? process.env
-    : {
-        ...process.env,
-        FALLOW_TYPE_AWARE_BIN: companion,
-        // Marks the wiring as launcher-provided node_modules resolution so
-        // `type-aware status` does not report it as a user-set override.
-        FALLOW_TYPE_AWARE_BIN_SOURCE: "npm-wrapper",
-      };
+  if (companion === undefined) return process.env;
+
+  const command = typeAwareCommand(companion, commandOptions);
+  const environment = {
+    ...process.env,
+    FALLOW_TYPE_AWARE_BIN: command.binary,
+    // Marks the wiring as launcher-provided node_modules resolution so
+    // `type-aware status` does not report it as a user-set override.
+    FALLOW_TYPE_AWARE_BIN_SOURCE: "npm-wrapper",
+  };
+  if (command.script) {
+    environment.FALLOW_TYPE_AWARE_SCRIPT = command.script;
+  } else {
+    delete environment.FALLOW_TYPE_AWARE_SCRIPT;
+  }
+  return environment;
 }
 
 // Swallow EPIPE on stdout. When fallow's output is piped into a reader that