fallow 3.17.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.17.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": [
@@ -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",
@@ -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.17.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.17.0",
-    "@fallow-cli/darwin-x64": "3.17.0",
-    "@fallow-cli/linux-x64-gnu": "3.17.0",
-    "@fallow-cli/linux-arm64-gnu": "3.17.0",
-    "@fallow-cli/linux-x64-musl": "3.17.0",
-    "@fallow-cli/linux-arm64-musl": "3.17.0",
-    "@fallow-cli/win32-arm64-msvc": "3.17.0",
-    "@fallow-cli/win32-x64-msvc": "3.17.0",
-    "fallow-type-aware": "3.17.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/sentinel-path.test.js

@@ -77,7 +77,7 @@ test("resolveSentinelPath falls back to FALLOW_VERIFY_CACHE_DIR when platform pk
   const cacheDir = mkTmp();
   try {
     const result = resolveSentinelPath({
-      platformPkgDir: "/dev/null/not-a-dir",
+      platformPkgDir: path.join(cacheDir, "missing-platform-package"),
       packageName: "@fallow-cli/darwin-arm64",
       env: { FALLOW_VERIFY_CACHE_DIR: cacheDir },
     });
@@ -220,12 +220,19 @@ test("resolveSentinelPath honors injected isWritable + ensureDir for full test i
 test("resolveSentinelPath skips cache-dir-env when ensureDir fails for it", () => {
   // FALLOW_VERIFY_CACHE_DIR points at a non-creatable path, XDG points at a
   // creatable one. Confirm the resolver moves past the env override.
+  //
+  // A directory nested under a regular FILE is the portable way to make mkdir
+  // fail: `/dev/null/inside/a/file` only refuses on POSIX, and on Windows the
+  // recursive mkdir succeeds against the current drive, which both defeats the
+  // assertion and creates C:\dev outside any temp directory.
   const homeDir = mkTmp();
+  const blocker = path.join(homeDir, "not-a-directory");
+  fs.writeFileSync(blocker, "");
   try {
     const result = resolveSentinelPath({
       platformPkgDir: undefined,
       packageName: "@fallow-cli/darwin-arm64",
-      env: { FALLOW_VERIFY_CACHE_DIR: "/dev/null/inside/a/file" },
+      env: { FALLOW_VERIFY_CACHE_DIR: path.join(blocker, "inside", "a", "file") },
       homedir: homeDir,
       platform: "darwin",
     });

package/scripts/verify-binary.test.js

@@ -239,10 +239,20 @@ test("verifyBinaryAt uses the embedded production public key", () => {
   }
 });
 
+// Mirror binaryTargetsForPlatform: the suffix comes from the platformId under
+// test, never from the live process.platform. A `dirOverride` run without an
+// explicit platformId is labelled "test-platform" by
+// resolvePlatformPackageForVerify, so the binary it looks for is plain `fallow`
+// on every host -- a fixture keyed off process.platform writes `fallow.exe` on a
+// Windows host and the verify then finds nothing.
+function extForPlatformId(platformId) {
+  return typeof platformId === "string" && platformId.startsWith("win32") ? ".exe" : "";
+}
+
 function makePlatformDir(privateKey, options) {
   const opts = options || {};
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), "fallow-vbtest-"));
-  const ext = process.platform === "win32" ? ".exe" : "";
+  const ext = extForPlatformId(opts.platformId);
   for (const base of ["fallow"]) {
     const binaryPath = path.join(dir, `${base}${ext}`);
     const content = Buffer.from(`mock ${base} contents`);
@@ -328,6 +338,42 @@ test("verifyInstalled with dirOverride returns ok when every binary verifies", a
   assert.equal(result.package, "<override>");
 });
 
+// binaryTargetsForPlatform reads windows-ness off the platformId so a Windows
+// verify can be synthesized anywhere. Nothing exercised that, which left the
+// `.exe` target unverified on Linux CI and unverified on Windows too.
+test("verifyInstalled verifies the .exe target for a win32 platformId on any host", async (t) => {
+  const { privateKey, rawPub } = makeKeypair();
+  const platformId = "win32-x64-msvc";
+  const dir = makePlatformDir(privateKey, { platformId });
+  t.after(() => cleanup(dir));
+  assert.ok(fs.existsSync(path.join(dir, "fallow.exe")), "fixture must write the .exe target");
+
+  const result = await verifyInstalled({
+    dirOverride: dir,
+    platformId,
+    verifyFn: (p) => _verifyWithKey(p, rawPub),
+    digestProvider: makeDigestProvider(dir),
+  });
+  assert.equal(result.ok, true);
+});
+
+test("verifyInstalled reports the .exe name when a win32 signature is absent", async (t) => {
+  const { privateKey, rawPub } = makeKeypair();
+  const platformId = "win32-arm64-msvc";
+  const dir = makePlatformDir(privateKey, { platformId, skipSigFor: "fallow" });
+  t.after(() => cleanup(dir));
+
+  const result = await verifyInstalled({
+    dirOverride: dir,
+    platformId,
+    verifyFn: (p) => _verifyWithKey(p, rawPub),
+    digestProvider: makeDigestProvider(dir),
+  });
+  assert.equal(result.ok, false);
+  assert.equal(result.code, "sig-missing");
+  assert.match(result.message, /fallow\.exe/);
+});
+
 test("verifyInstalled resolves a global npm install from the fallow package directory", async (t) => {
   const pkg = currentPlatformPackage();
   if (!pkg) {
@@ -460,8 +506,8 @@ test("verifyInstalled honors FALLOW_SKIP_BINARY_VERIFY", async (t) => {
   assert.equal(result.skipped, true);
 });
 
-function computeDigestsForDir(dir) {
-  const ext = process.platform === "win32" ? ".exe" : "";
+function computeDigestsForDir(dir, platformId) {
+  const ext = extForPlatformId(platformId);
   const out = {};
   for (const base of ["fallow"]) {
     const fileName = `${base}${ext}`;
@@ -581,7 +627,7 @@ test("verifyInstalled returns digest-mismatch when the embedded digest disagrees
   const { privateKey, rawPub } = makeKeypair();
   const dir = makePlatformDir(privateKey);
   t.after(() => cleanup(dir));
-  const ext = process.platform === "win32" ? ".exe" : "";
+  const ext = extForPlatformId();
   writeManifest(dir, {
     name: "@fallow-cli/x",
     version: "1.0.0",

package/skills/fallow/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: fallow
-description: Codebase intelligence for TypeScript and JavaScript. Static analysis of code and styles reports changed-code risk, cleanup opportunities, duplication, circular dependencies, complexity hotspots, architecture boundaries, design-system drift, feature flags, and opt-in security candidates. Runtime coverage can merge production execution data for hot-path review, cold-path deletion confidence, and stale-flag evidence. 123 framework plugins, zero configuration, sub-second static analysis. Use when asked to audit PR risk, find unused code or dependencies, detect duplicates, check styling consistency, inspect architecture boundaries, merge runtime coverage, auto-fix supported issues, or run fallow.
+description: Codebase intelligence for TypeScript and JavaScript. Static analysis of code and styles reports changed-code risk, cleanup opportunities, duplication, circular dependencies, complexity hotspots, architecture boundaries, design-system drift, feature flags, and opt-in security candidates. Runtime coverage can merge production execution data for hot-path review, cold-path deletion confidence, and stale-flag evidence. Broad framework plugin coverage, zero configuration, sub-second static analysis. Use when asked to audit PR risk, find unused code or dependencies, detect duplicates, check styling consistency, inspect architecture boundaries, merge runtime coverage, auto-fix supported issues, or run fallow.
 license: MIT
 ---
 
 # Fallow: codebase intelligence for TypeScript and JavaScript
 
-Codebase intelligence for TypeScript and JavaScript. The static layer analyzes code and styles and reports quality, changed-code risk, cleanup opportunities, circular dependencies, code duplication, complexity hotspots, architecture boundary violations, design-system styling drift, feature flag patterns, and opt-in security candidates. Runtime coverage merges production execution data into the same `fallow health` report for hot-path review, cold-path deletion confidence, and stale-flag evidence, with a single local capture available by default and continuous/cloud runtime monitoring available as an optional mode. 123 framework plugins, zero configuration, sub-second static analysis.
+Codebase intelligence for TypeScript and JavaScript. The static layer analyzes code and styles and reports quality, changed-code risk, cleanup opportunities, circular dependencies, code duplication, complexity hotspots, architecture boundary violations, design-system styling drift, feature flag patterns, and opt-in security candidates. Runtime coverage merges production execution data into the same `fallow health` report for hot-path review, cold-path deletion confidence, and stale-flag evidence, with a single local capture available by default and continuous/cloud runtime monitoring available as an optional mode. Broad framework plugin coverage, zero configuration, sub-second static analysis.
 
 ## When to Use
 - Find cleanup opportunities: unused files, exports, types, members, dependencies, or stale flags.
@@ -42,8 +42,8 @@ cargo install fallow-cli   # build from source
 
 ## Agent Rules
 
-1. **Always use `--format json --quiet 2>/dev/null`** for machine-readable output and parse it as JSON. Compact JSON is the default; never depend on whitespace or add `--pretty` in agent pipelines. The `2>/dev/null` discards stderr so progress messages and threshold warnings don't corrupt the JSON on stdout. Never use `2>&1`
-2. **Always append `|| true`** to every fallow command. Exit code 1 means "issues found" (normal), not a runtime error. Without `|| true`, the Bash tool treats exit 1 as failure and cancels parallel commands. Only exit code 2 is a real error (invalid config, parse failure)
+1. **Always use `--format json --quiet`** for machine-readable output and parse stdout as JSON. Compact JSON is the default; never depend on whitespace or add `--pretty` in agent pipelines. Keep stderr separate so diagnostics remain visible; never merge it into the JSON stream with `2>&1`.
+2. **Preserve and interpret the exit status.** Codes 0 and 1 are successful analysis outcomes: 0 is clean and 1 means findings. Treat every other code according to `fallow schema.exit_codes`. Do not force a successful status, because that hides validation, license, setup, network, and security-gate outcomes.
 3. **Use `--explain`** to include a `_meta` object in JSON output with metric definitions, ranges, and interpretation hints. In human format, `--explain` prints a `Description:` line under each section header.
 4. **Use the root `kind` field** to identify typed JSON envelopes (`dead-code`, `dead-code-grouped`, `health`, `dupes`, `combined`, `audit`, etc.).
 5. **Use issue type filters** (`--unused-exports`, `--unused-files`, etc.) to limit output scope
@@ -160,8 +160,8 @@ Run `fallow <command> --help` for the full flag list per command (see also refer
 | `unused-catalog-entry` | `--unused-catalog-entries` | yes | - | `pnpm-workspace.yaml` entries no workspace package.json references via `catalog:` (default `warn`) |
 | `empty-catalog-group` | `--empty-catalog-groups` | - | - | Named `catalogs.<name>:` groups in `pnpm-workspace.yaml` with no entries. Top-level `catalog:` placeholders are ignored. Default `warn`. |
 | `unresolved-catalog-reference` | `--unresolved-catalog-references` | - | - | `package.json` references to `catalog:` / `catalog:<name>` whose catalog does not declare the package; `pnpm install` would fail. Default `error`. Suppress via `ignoreCatalogReferences: [{ package, catalog?, consumer? }]` in fallow config (package.json has no comment syntax). |
-| `unused-dependency-override` | `--unused-dependency-overrides` | - | - | `pnpm-workspace.yaml#overrides` / `package.json#pnpm.overrides` entries whose target package is not declared by any workspace `package.json` and is not present in `pnpm-lock.yaml`. Default `warn`. When the lockfile is missing or unreadable the check degrades to a manifest-only fallback and every finding carries a `hint` reminding consumers to verify before removal. Suppress via `ignoreDependencyOverrides: [{ package, source? }]` in fallow config. |
-| `misconfigured-dependency-override` | `--misconfigured-dependency-overrides` | - | - | `pnpm.overrides` entries whose key is unparsable (empty, dangling separators, malformed selectors) or value is missing/empty. `pnpm install` would fail. Default `error`. Suppression: same `ignoreDependencyOverrides` config rule. |
+| `unused-dependency-override` | `--unused-dependency-overrides` | - | - | Entries in `pnpm-workspace.yaml#overrides`, `package.json#pnpm.overrides`, npm or Bun `package.json#overrides`, or Bun `package.json#resolutions` whose target package is not declared by any workspace `package.json` and is not present in the active readable lockfile. Default `warn`. pnpm and npm projects without a readable lockfile degrade to a manifest-only fallback with a verification `hint`; Bun projects with only binary `bun.lockb` fail closed and emit no finding. Suppress via `ignoreDependencyOverrides: [{ package, source? }]` in fallow config. |
+| `misconfigured-dependency-override` | `--misconfigured-dependency-overrides` | - | - | Package-manager override entries whose key is unparsable or whose value is missing or empty. The active package manager may reject or ignore the entry. Default `error`. Suppression: same `ignoreDependencyOverrides` config rule. |
 | `invalid-client-export` | - | - | `// fallow-ignore-next-line invalid-client-export` | "use client" file exports a server-only / route-config name; Requires the project to declare next |
 | `mixed-client-server-barrel` | - | - | `// fallow-ignore-next-line mixed-client-server-barrel` | Barrel re-exports both a "use client" module and a server-only module; Requires the project to declare next |
 | `misplaced-directive` | - | - | `// fallow-ignore-next-line misplaced-directive` | "use client" / "use server" directive is not in the leading position and is ignored; Requires the project to declare next |
@@ -257,7 +257,7 @@ fallow list --entry-points --format json --quiet
 fallow list --plugins --format json --quiet
 ```
 
-Shows detected entry points and active framework plugins (123 built-in: Next.js, Vite, Ember, Wuchale, Jest, Storybook, Tailwind, PandaCSS, Contentlayer, tap, tsd, etc.).
+Shows detected entry points and active framework plugins. Read `fallow schema.plugins.count` when the exact current registry size matters.
 
 ### Production-only analysis
 ```bash
@@ -428,11 +428,7 @@ fallow hooks install --target git   # pre-commit gate; --branch <ref> sets the f
 
 ## Exit Codes
 
-| Code | Meaning |
-|------|---------|
-| 0 | Success, no error-severity issues |
-| 1 | Error-severity issues found |
-| 2 | Runtime error (invalid config, parse failure, or `fix` without `--yes` in non-TTY) |
+Codes 0 and 1 are successful analysis outcomes: 0 is clean and 1 means findings. Read `fallow schema.exit_codes` for validation, resource, runtime, network, security-gate, and upload failures instead of maintaining another copied table.
 
 When `--format json` is active and exit code is 2, errors are emitted as JSON on stdout:
 ```json
@@ -441,7 +437,7 @@ When `--format json` is active and exit code is 2, errors are emitted as JSON on
 
 ## Configuration
 
-Fallow reads config from project root: `.fallowrc.json` > `.fallowrc.jsonc` > `fallow.toml` > `.fallow.toml`. Both `.fallowrc.json` and `.fallowrc.jsonc` accept JSON-with-comments syntax (same parser); the `.jsonc` extension lets editors auto-detect JSONC syntax highlighting. Most projects work with zero configuration thanks to 123 auto-detecting framework plugins.
+Fallow reads config from project root: `.fallowrc.json` > `.fallowrc.jsonc` > `fallow.toml` > `.fallow.toml`. Both `.fallowrc.json` and `.fallowrc.jsonc` accept JSON-with-comments syntax (same parser); the `.jsonc` extension lets editors auto-detect JSONC syntax highlighting. Most projects work with zero configuration thanks to auto-detecting framework plugins; read `fallow schema.plugins` for the current registry.
 
 ```jsonc
 {
@@ -478,7 +474,7 @@ export const deprecatedHelper = () => {};
 ## Key Gotchas
 
 - **`fix --yes` is required** in non-TTY (agent) environments. Without it, `fix` exits with code 2
-- **Zero config by default.** 123 framework plugins auto-detect, including Wuchale config, Contentlayer content roots, tap and tsd test entry points. Don't create config unless customization is needed
+- **Zero config by default.** Built-in framework plugins auto-detect, including Wuchale config, Contentlayer content roots, tap and tsd test entry points. Read `fallow schema.plugins` for the current registry and don't create config unless customization is needed
 - **Syntactic analysis only.** No TypeScript compiler, so fully dynamic `import(variable)` is not resolved
 - **Function overloads are deduplicated.** TypeScript function overload signatures are merged into a single export (not reported as separate unused exports)
 - **Re-export chains are resolved.** Exports through barrel files are tracked, not falsely flagged

package/skills/fallow/references/cli-reference.md

@@ -89,8 +89,8 @@ Common global flags for this command: [`--format`](#global-flags), [`--quiet`](#
 | `--unused-catalog-entries` | Unused pnpm catalog entries |
 | `--empty-catalog-groups` | Empty named pnpm catalog groups |
 | `--unresolved-catalog-references` | Package references to missing pnpm catalog entries |
-| `--unused-dependency-overrides` | Unused pnpm dependency overrides |
-| `--misconfigured-dependency-overrides` | Malformed pnpm dependency overrides |
+| `--unused-dependency-overrides` | Unused package-manager dependency overrides |
+| `--misconfigured-dependency-overrides` | Misconfigured package-manager dependency overrides |
 <!-- generated:flags:dead-code-filters:end -->
 ### Examples
 
@@ -298,7 +298,7 @@ fallow list --workspaces --format json --quiet
 fallow workspaces --format json --quiet  # alias of `fallow list --workspaces`
 ```
 
-The `--workspaces` JSON output carries `workspaces[]` (name, project-root-relative path, `is_internal_dependency` bool) plus `workspace_diagnostics[]`. Each diagnostic has a `kind` discriminator (`undeclared-workspace`, `malformed-package-json`, `glob-matched-no-package-json`, `malformed-tsconfig`, `tsconfig-reference-dir-missing`) with a typed payload (`error`, `pattern`, or none). The same `workspace_diagnostics[]` array is also surfaced on `fallow dead-code --format json`, `fallow dupes --format json`, and `fallow health --format json` envelopes (omitted when empty). A malformed ROOT `package.json` exits 2 at config load; everything else warns and continues.
+The `--workspaces` JSON output carries `workspaces[]` (name, project-root-relative path, `is_internal_dependency` bool) plus `workspace_diagnostics[]`. Each diagnostic has a `kind` discriminator (`undeclared-workspace`, `malformed-package-json`, `glob-matched-no-package-json`, `malformed-tsconfig`, `tsconfig-reference-dir-missing`, `malformed-pnpm-workspace-yaml`, `skipped-large-file`, `skipped-minified-file`, `source-read-failure`, `bun-lockb-override-resolution-skipped`) with a typed payload (`error`, `pattern`, or none), and a `path` that is project-root-relative with forward slashes on every envelope that carries the array. The same `workspace_diagnostics[]` array is also surfaced on the `fallow dead-code --format json`, `fallow dupes --format json`, and `fallow health --format json` envelopes, at the top level of the bare combined `fallow --format json` envelope, on `fallow audit --format json` under `dead_code`, and on the `audit-brief` envelope shared by `fallow review --format json` and `fallow audit --brief --format json`, also under `dead_code` (omitted when empty). The combined carrier is the envelope root, not a section, so `--skip check`, `--only health`, and `--only dupes` all still report what their analyses recorded. The combined root is the union of what every analysis in the run recorded, deduplicated on the whole `kind` (typed payload included) plus `path`, so two overlapping globs still report the same package-less directory once per `pattern` (a declared glob's no-op `./` prefix is normalised away, so one glob written `"./apps/**"` in `package.json` and `apps/**` in `pnpm-workspace.yaml` stays one entry): a combined run walks the project once per analysis, and a per-analysis `production` mode (`production: { deadCode, health, dupes }`, `--production-health`) can give those walks different file sets, so only the union reports what the run as a whole saw. Each analysis contributes the workspace-discovery list its own config load produced, the same list `fallow list --workspaces` reports, so the combined root can carry an `undeclared-workspace` or `glob-matched-no-package-json` entry that the standalone `dead-code`, `check`, `health`, and `dupes` envelopes, which read the process diagnostics registry instead, do not. `fallow audit --format json` and the `audit-brief` envelope are on the same broad side: they fold the dead-code analysis's own list into their `dead_code.workspace_diagnostics[]`, so they too report an `undeclared-workspace` entry the standalone envelopes miss. The CLI and the programmatic route (MCP code mode, NAPI, embedders) agree on everything an analysis records: both folds close with the same process-registry read, which covers what an analysis records after its section captured its list (a `source-read-failure`, or the analysis-stage kinds a health run's own dead-code precompute records) and skips `skipped-large-file` and `skipped-minified-file`, since those reach an envelope only from the walk that recorded them. The two analysis-stage kinds (`malformed-pnpm-workspace-yaml`, `bun-lockb-override-resolution-skipped`) are recorded by the dead-code analyze pass, so they only appear on runs that include it: `fallow dupes --format json` and `fallow --only dupes` report the workspace-discovery and source-discovery kinds alone. A malformed ROOT `package.json` exits 2 at config load; everything else warns and continues.
 
 The `--boundaries` JSON output carries `boundaries.logical_groups[]` alongside the existing `zones[]` / `rules[]` arrays. Each logical-group entry surfaces a user-authored `autoDiscover` parent zone (which expansion otherwise flattens into per-child zones like `features/auth` / `features/billing`): `name`, `children`, `auto_discover` (verbatim user strings), `status` (`ok` / `empty` / `invalid_path`), `source_zone_index`, summed `file_count`, optional `authored_rule` (the pre-expansion `{ allow, allowTypeOnly }` keyed on the parent), optional `fallback_zone` cross-reference when the parent also kept its own `patterns` (Bulletproof case), optional `merged_from` (parent zone indices when the user declared the same parent name twice; surfaces the duplicate in JSON instead of only in `tracing::warn!`), optional `original_zone_root` (echo of the parent's `root` subtree scope for monorepo patchers), and optional `child_source_indices` (parallel to `children`, attributing each child to a specific `auto_discover` entry when multiple paths were authored). The full shape is documented in `docs/output-schema.json` under `ListBoundariesOutput`.
 
@@ -838,8 +838,8 @@ Audits changed files for dead code, complexity, duplication, and styling. Return
 | `--health-baseline` | `string` | - | Baseline file (produced by `fallow health --save-baseline`). Pre-existing complexity findings are excluded from the verdict. |
 | `--dupes-baseline` | `string` | - | Baseline file (produced by `fallow dupes --save-baseline`). Pre-existing clone groups are excluded from the verdict. |
 | `--max-crap` | `string` | - | Forwarded to the health sub-analysis. Functions meeting or exceeding this CRAP score cause audit to fail. Same formula as `health --max-crap`. Pair with coverage data for accurate per-function CRAP. |
-| `--coverage` | `string` | - | Path to Istanbul-format coverage data (`coverage-final.json`) for accurate per-function CRAP scores in the health sub-analysis. Same format and semantics as `health --coverage`. Also configurable via `FALLOW_COVERAGE`. Relative paths resolve against `--root`. |
-| `--coverage-root` | `string` | - | Absolute prefix to strip from file paths in coverage data before prepending the project root. Also configurable via `FALLOW_COVERAGE_ROOT`. Use when coverage was generated under a different checkout root in CI / Docker (e.g., `/home/runner/work/myapp` on GitHub Actions). |
+| `--coverage` | `string` | - | Path to Istanbul-format coverage data (`coverage-final.json`) for accurate per-function CRAP scores in the health sub-analysis. Same format and semantics as `health --coverage`. Also configurable via `FALLOW_COVERAGE`, then `health.coverage` (the same chain as `fallow health`). Relative paths resolve against `--root`. |
+| `--coverage-root` | `string` | - | Absolute prefix to strip from file paths in coverage data before prepending the project root. Also configurable via `FALLOW_COVERAGE_ROOT`, then `health.coverageRoot`. Use when coverage was generated under a different checkout root in CI / Docker (e.g., `/home/runner/work/myapp` on GitHub Actions). |
 | `--no-css` | `bool` | `false` | Disable styling analytics in audit |
 | `--css-deep` | `bool` | `false` | Enable deep CSS analysis for audit explicitly: project-wide styling reachability, narrowed back to changed anchors. Deep CSS is on by default; use this to override `audit.cssDeep = false` |
 | `--no-css-deep` | `bool` | `false` | Disable deep CSS analysis while keeping local styling analytics on |

package/skills/fallow/references/gotchas.md

@@ -23,7 +23,7 @@ Always preview with `--dry-run` before applying. This is a destructive operation
 
 ## Don't Create Config Unless Needed
 
-Fallow works with zero configuration for most projects thanks to 123 auto-detecting framework plugins. Creating an unnecessary config file can mask issues or override detection behavior.
+Fallow works with zero configuration for most projects thanks to auto-detecting framework plugins. Read `fallow schema.plugins` for the current registry. Creating an unnecessary config file can mask issues or override detection behavior.
 
 ```bash
 # WRONG: creating config for a standard Next.js project

package/skills/fallow/references/mcp.md

@@ -38,7 +38,7 @@ When using fallow via MCP (`fallow-mcp`), the following tools are available:
 | `impact` | introspection | free | `fallow impact --format json --quiet` | `root` | Read the local, opt-in Fallow Impact value report (`fallow impact --format json`). Runs no analysis: current surfacing counts, trend since the last recorded run, pre-commit gate containment, and (on impact v1.5+) resolved/suppressed attribution. History is read from a per-project file in the user's private config dir (never inside the repo). Read-only and `root`-only; the mutating `enable` / `disable` / `default` lifecycle is not exposed. A never-enabled project returns a populated `{"enabled": false, ...}` report (never `{}`); branch on `enabled` and `enabled_source` (`project` / `user` / `default`) then `record_count`, recommending `fallow impact enable` only when `explicit_decision` is `false` (never asked) and staying silent when `true` (deliberately disabled here). Local-developer signal: fallow never records in CI, so empty there and not a CI metric |
 | `impact_all` | introspection | free | `fallow impact --all --format json --quiet` | `sort`, `limit` | Roll every tracked fallow project on this machine into one cross-repo value report (hashed keys plus basename labels, never paths; local-dev only) |
 | `trace_export` | trace | free | `fallow dead-code --trace <file:export> --format json --quiet` | `file`, `export_name` | Trace why an export is used or unused (`fallow dead-code --trace FILE:EXPORT_NAME --format json`). Required `file` and `export_name`. Returns file reachability, entry-point status, direct references, re-export chains, and a reason string. If `export_name` is a class / enum / store MEMBER, returns a member trace instead (`member_name`, `member_kind`, `owner_export`, `owner_is_used`) plus a `--unused-<kind>-members` pointer; branch on field presence. Use before deleting a supposedly-unused export or debugging an unused-class-member finding |
-| `trace_symbol` | trace | free | `fallow dead-code --type-aware --trace <file:export> --format json --quiet` | `file`, `export_name`, `type_aware_projects`, `type_aware_require` | 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. |
+| `trace_symbol` | trace | free | `fallow dead-code --type-aware --trace <file:export> --format json --quiet` | `file`, `export_name`, `type_aware_projects`, `type_aware_require` | 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. |
 | `symbol_impact` | impact | free | `fallow dead-code --type-aware --symbol-impact <file:export-or-class.member> --format json --quiet` | `file`, `export_name`, `class_name`, `member_name`, `type_aware_projects`, `type_aware_require` | Return exact-symbol consumers, affected files, and targeted tests for a TypeScript export or exported class method. Select either `export_name`, or both `class_name` and `member_name`. Advisory change-impact evidence, not a substitute for `tsc` or Oxlint |
 | `trace_file` | trace | free | `fallow dead-code --trace-file <file> --format json --quiet` | `file` | Trace all graph edges for a file (`fallow dead-code --trace-file PATH --format json`). Required `file`. Returns reachability, exports, imports-from, imported-by, and re-exports. Use to decide whether a file is isolated, barrel-only, or imported by live entry points |
 | `impact_closure` | trace | free | `fallow dead-code --impact-closure <path> --format json --quiet` | `path` | Trace the transitive affected-but-not-in-diff set and coordination gaps for one file. Supports `root`, `config`, `production`, `workspace`, `no_cache`, and `threads`. Use as review-planning evidence for a file contract, not proof that affected files are wrong |
@@ -46,6 +46,29 @@ When using fallow via MCP (`fallow-mcp`), the following tools are available:
 | `trace_clone` | trace | free | `fallow dupes --trace <file:line> --format json --quiet` | `file`, `line`, `fingerprint`, `near`, `min_occurrences` | Deep-dive a duplicate-code clone group (`fallow dupes --trace <spec> --format json`). Address by exactly one of: `file` + `line` (a source location), or `fingerprint` (a `dup:<id>` from a prior `find_dupes` `clone_groups[].fingerprint`, usually `dup:<8hex>` and widened only on rare report collisions). Returns the matched clone instance plus every clone group containing it; each traced group carries its `fingerprint`, an extract-function `suggestion` with estimated savings, and a best-effort `suggested_name` (omitted when no confident name). Supports `mode`, `near`, `min_tokens`, `min_lines`, `min_occurrences`, `threshold`, `skip_local`, `cross_language`, `ignore_imports`. Use the same `near` value as the originating `find_dupes` call. Use to consolidate duplication when you need exact sibling locations and a refactor target |
 <!-- generated:mcp-tools:end -->
 
+## How type-aware proof relates to the root trace
+
+`trace_symbol` is the only tool that returns a checker-backed `semantic` block
+next to a syntactic root trace. The checker resolves actual reads through local
+aliases, import types, namespace-qualified names, and barrels to the exact type
+or value declaration. Import and re-export declarations alone are not reads.
+The root trace stays authoritative for graph reachability and star ambiguity,
+and its optional `direct_references_by_namespace` keeps type and value evidence
+separate without changing the selected root `namespace`. Type-aware
+reconciliation fails closed: unreachable-only, re-export-only, or
+different-declaration evidence cannot suppress a syntactic finding. Treat an
+ambiguous root as an abstention, and investigate any remaining mismatch before
+deleting a symbol.
+
+`symbol_impact` carries no `semantic` block and no root trace. Its top-level
+checker evidence uses the same declaration-safe alias and namespace resolution
+as `trace_symbol`. A listed consumer's `relation` names the traced symbol's own
+lane, not the consumer's syntax. Confirm a clean impact result with
+`trace_export` or `trace_symbol` before deletion when the graph reports
+ambiguity or reachable references.
+
+`trace_export` never carries a `semantic` block: it is API-backed in-process and answers from the graph alone.
+
 ## Runtime source-map confidence for cloud runtime tools
 
 | Values | Meaning | Agent action |

package/skills/fallow/references/patterns.md

@@ -645,7 +645,7 @@ Focus on findings that are BOTH dead code and duplicated:
 
 ## Custom Plugin Setup
 
-For frameworks not covered by the 123 built-in plugins.
+For frameworks not covered by the current built-in registry from `fallow schema.plugins`.
 
 ### Option 1: Inline framework config
 
@@ -717,7 +717,7 @@ fallow dead-code --format sarif --quiet > fallow.sarif
 fallow dead-code --ci > fallow.sarif
 ```
 
-The `--ci` flag is equivalent to `--format sarif --fail-on-issues --quiet`. Note: `--fail-on-issues` means exit code 1 if issues exist, in CI scripts use `continue-on-error: true` or `|| true` to ensure the SARIF upload step still runs.
+The `--ci` flag is equivalent to `--format sarif --fail-on-issues --quiet`. Exit code 1 means findings exist. Capture that status, let the SARIF upload step run, then reapply the captured status in a final gate step. Do not discard every outcome, because validation and execution failures need to remain distinguishable from findings.
 
 ---
 

package/types/output-contract.d.ts

@@ -363,9 +363,9 @@ type: "jsdoc_tag"
  */
 export type DependencyOverrideSource = ("pnpm-workspace.yaml" | "package.json")
 /**
- * Why a dependency-override entry is misconfigured. `pnpm install` would
- * either fail at install time or silently no-op on these entries; surfacing
- * them statically catches the issue before pnpm does.
+ * Why a dependency-override entry is misconfigured. The active package
+ * manager may fail at install time or silently no-op on these entries;
+ * surfacing them statically catches the issue first.
  */
 export type DependencyOverrideMisconfigReason = ("unparsable-key" | "empty-value")
 /**
@@ -441,6 +441,12 @@ kind: "skipped-minified-file"
  */
 error: string
 kind: "source-read-failure"
+} | {
+kind: "bun-lockb-override-resolution-skipped"
+} | {
+kind: "bun-lock-override-resolution-skipped"
+} | {
+kind: "bun-resolutions-shadowed-by-overrides"
 })
 /**
  * Discriminant for [`CloneGroupAction::kind`]. Mirrors the action types
@@ -2283,20 +2289,23 @@ empty_catalog_groups?: EmptyCatalogGroupFinding[]
  */
 unresolved_catalog_references?: UnresolvedCatalogReferenceFinding[]
 /**
- * Entries in pnpm-workspace.yaml's overrides: section, package.json's
- * pnpm.overrides block, or package.json's top-level npm overrides object,
+ * Entries in pnpm-workspace.yaml's overrides section, package.json's
+ * pnpm.overrides block, npm or Bun's top-level overrides object, or Bun's
+ * top-level resolutions object,
  * whose target package is not declared by any workspace package and is
- * not present in pnpm-lock.yaml or package-lock.json. Default severity
- * is warn because projects without a readable lockfile fall back to
- * manifest-only checks; the hint field flags those conservative cases.
+ * not present in pnpm-lock.yaml, package-lock.json, npm-shrinkwrap.json,
+ * or bun.lock. Default severity is warn because projects without a
+ * readable lockfile fall back to manifest-only checks; the hint field
+ * flags those conservative cases. When the only lockfile is bun's binary
+ * bun.lockb, resolution cannot be read and the check emits nothing.
  * Wrapped in [`UnusedDependencyOverrideFinding`].
  */
 unused_dependency_overrides?: UnusedDependencyOverrideFinding[]
 /**
- * pnpm.overrides or npm overrides entries whose key or value does not
- * parse as a valid override spec (empty key, empty value, malformed
- * selector, unbalanced parent matcher). The package manager will reject
- * these at install time. Default severity is error. Wrapped in
+ * Package-manager override or resolution entries whose key or value does
+ * not parse in the declaration source's grammar (empty key, empty value,
+ * malformed selector, unbalanced parent matcher). The package manager may
+ * reject or ignore these at install time. Default severity is error. Wrapped in
  * [`MisconfiguredDependencyOverrideFinding`].
  */
 misconfigured_dependency_overrides?: MisconfiguredDependencyOverrideFinding[]
@@ -2454,7 +2463,24 @@ regression?: (RegressionResult | null)
  */
 _meta?: (Meta | null)
 /**
- * Workspace-discovery diagnostics surfaced during config load.
+ * Non-fatal diagnostics about the project itself, from all three stages
+ * that record them (issue #473):
+ *
+ * - workspace discovery, at config load: `undeclared-workspace`,
+ *   `malformed-package-json`, `glob-matched-no-package-json`,
+ *   `malformed-tsconfig`, `tsconfig-reference-dir-missing`;
+ * - source discovery, during the file walk: `skipped-large-file`,
+ *   `skipped-minified-file`, `source-read-failure`;
+ * - dead-code analysis, from the dependency-catalog and override
+ *   detectors: `malformed-pnpm-workspace-yaml`,
+ *   `bun-lockb-override-resolution-skipped`.
+ *
+ * Analysis-stage kinds therefore reach only the envelopes whose run
+ * includes a dead-code analyze pass, never a standalone
+ * `fallow dupes --format json`. `path` is project-root-relative with
+ * forward slashes; the array is omitted when empty. The same list is
+ * repeated on each top-level command's envelope so single-command
+ * consumers see it without having to look at a separate top-level field.
  */
 workspace_diagnostics?: WorkspaceDiagnostic[]
 /**
@@ -2638,12 +2664,12 @@ empty_catalog_groups: number
  */
 unresolved_catalog_references: number
 /**
- * Pnpm `overrides:` entries whose target package is not declared by any
- * workspace package and not present in the lockfile.
+ * Package-manager overrides whose target package is not declared by any
+ * workspace package and not present in the active readable lockfile.
  */
 unused_dependency_overrides: number
 /**
- * Pnpm `overrides:` entries whose key or value cannot be parsed.
+ * Package-manager overrides whose key or value cannot be parsed.
  */
 misconfigured_dependency_overrides: number
 /**
@@ -3886,7 +3912,7 @@ parent_package?: (string | null)
  */
 version_constraint?: (string | null)
 /**
- * The right-hand side of the entry: the version pnpm should force.
+ * The right-hand side of the entry: the version the package manager should force.
  */
 version_range: string
 source: DependencyOverrideSource
@@ -9036,6 +9062,18 @@ is_used: boolean
  * Files that reference this export directly.
  */
 direct_references: ExportReference[]
+/**
+ * Reachable direct references grouped by namespace. This is additive to
+ * `namespace` and `direct_references`, whose winning-lane meaning remains
+ * unchanged for backwards compatibility.
+ */
+direct_references_by_namespace?: NamespacedExportReferences[]
+/**
+ * A star-export collision that makes the traced name ambiguous. When
+ * present, `is_used: false` is an abstention rather than an unused-code
+ * verdict.
+ */
+star_export_ambiguity?: (StarExportAmbiguity | null)
 /**
  * Re-export chains that pass through this export.
  */
@@ -9062,6 +9100,36 @@ from_file: string
  */
 kind: string
 }
+/**
+ * Direct references that credit one namespace of an export binding.
+ */
+export interface NamespacedExportReferences {
+namespace: SemanticNamespace
+/**
+ * Number of reachable references in this namespace.
+ */
+reference_count: number
+/**
+ * Reachable references in deterministic graph order.
+ */
+references: ExportReference[]
+}
+/**
+ * The `export *` collision that keeps a name from being exported.
+ */
+export interface StarExportAmbiguity {
+/**
+ * Files that each declare a colliding declaration under the traced name
+ * (project-root-relative), sorted. These are the origins to fix: keep one,
+ * rename or explicitly re-export the rest.
+ */
+sources: string[]
+/**
+ * The namespaces the collision occurs in, type before value. A name can
+ * collide in type space, value space, or both.
+ */
+namespaces: SemanticNamespace[]
+}
 /**
  * A re-export chain showing how an export is propagated.
  */
@@ -9105,6 +9173,7 @@ member_kind: string
  * The export that declares this member (the class / enum / store name).
  */
 owner_export: string
+owner_namespace?: SemanticNamespace
 /**
  * Whether the owning export is considered used.
  */
@@ -9423,22 +9492,6 @@ export interface UnresolvedCallee {
 callee: string
 reason: UnresolvedReason
 }
-/**
- * The `export *` collision that keeps a name from being exported.
- */
-export interface StarExportAmbiguity {
-/**
- * Files that each declare a colliding declaration under the traced name
- * (project-root-relative), sorted. These are the origins to fix: keep one,
- * rename or explicitly re-export the rest.
- */
-sources: string[]
-/**
- * The namespaces the collision occurs in, type before value. A name can
- * collide in type space, value space, or both.
- */
-namespaces: SemanticNamespace[]
-}
 /**
  * Envelope emitted by `fallow --format review-github` / `review-gitlab`.
  */
@@ -9576,7 +9629,8 @@ comments: number
  */
 current_fingerprints: number
 /**
- * Distinct fingerprints found in existing comments.
+ * Distinct fingerprints with an open Fallow lifecycle, including
+ * provider-resolved discussions not yet closed by a Fallow marker.
  */
 existing_fingerprints: number
 /**
@@ -9584,7 +9638,7 @@ existing_fingerprints: number
  */
 new_fingerprints: number
 /**
- * Fingerprints commented earlier whose findings no longer exist.
+ * Fingerprints with open Fallow lifecycles whose findings no longer exist.
  */
 stale_fingerprints: number
 /**
@@ -9604,7 +9658,7 @@ provider_warning?: (string | null)
  */
 resolution_comments_posted: number
 /**
- * Stale discussion threads resolved (GitLab).
+ * Provider discussion threads resolved or re-closed.
  */
 threads_resolved: number
 /**
@@ -9914,8 +9968,10 @@ workspace_count: number
 workspaces: WorkspaceInfo[]
 /**
  * Workspace discovery diagnostics produced while reading workspace
- * declarations. Present for compatibility with the current wire contract,
- * even when empty.
+ * declarations. Paths are project-root-relative and use forward slashes,
+ * like `workspaces[].path` and like the `workspace_diagnostics[]` array on
+ * the analysis envelopes. Present for compatibility with the current wire
+ * contract, even when empty.
  */
 workspace_diagnostics: WorkspaceDiagnostic[]
 }
@@ -10090,7 +10146,10 @@ groups?: (HealthGroup[] | null)
  */
 _meta?: (Meta | null)
 /**
- * Workspace-discovery diagnostics surfaced during config load.
+ * Workspace-discovery, source-discovery, and analysis-stage diagnostics
+ * for the run. See `CheckOutput::workspace_diagnostics` for the full
+ * contract: the kinds each stage records, project-root-relative paths,
+ * omitted when empty.
  */
 workspace_diagnostics?: WorkspaceDiagnostic[]
 /**
@@ -10239,11 +10298,13 @@ groups?: (DuplicationGroup[] | null)
  */
 _meta?: (Meta | null)
 /**
- * Workspace-discovery diagnostics surfaced during config load
+ * Workspace-discovery and source-discovery diagnostics for the run
  * (issue #473). See `CheckOutput::workspace_diagnostics` for the full
  * contract; the same list is repeated on each top-level command's
  * envelope so single-command consumers see it without having to look at
- * a separate top-level field.
+ * a separate top-level field. A standalone `fallow dupes` run has no
+ * dead-code analyze pass, so the two analysis-stage kinds never appear
+ * here.
  */
 workspace_diagnostics?: WorkspaceDiagnostic[]
 /**
@@ -10592,20 +10653,23 @@ empty_catalog_groups?: EmptyCatalogGroupFinding[]
  */
 unresolved_catalog_references?: UnresolvedCatalogReferenceFinding[]
 /**
- * Entries in pnpm-workspace.yaml's overrides: section, package.json's
- * pnpm.overrides block, or package.json's top-level npm overrides object,
+ * Entries in pnpm-workspace.yaml's overrides section, package.json's
+ * pnpm.overrides block, npm or Bun's top-level overrides object, or Bun's
+ * top-level resolutions object,
  * whose target package is not declared by any workspace package and is
- * not present in pnpm-lock.yaml or package-lock.json. Default severity
- * is warn because projects without a readable lockfile fall back to
- * manifest-only checks; the hint field flags those conservative cases.
+ * not present in pnpm-lock.yaml, package-lock.json, npm-shrinkwrap.json,
+ * or bun.lock. Default severity is warn because projects without a
+ * readable lockfile fall back to manifest-only checks; the hint field
+ * flags those conservative cases. When the only lockfile is bun's binary
+ * bun.lockb, resolution cannot be read and the check emits nothing.
  * Wrapped in [`UnusedDependencyOverrideFinding`].
  */
 unused_dependency_overrides?: UnusedDependencyOverrideFinding[]
 /**
- * pnpm.overrides or npm overrides entries whose key or value does not
- * parse as a valid override spec (empty key, empty value, malformed
- * selector, unbalanced parent matcher). The package manager will reject
- * these at install time. Default severity is error. Wrapped in
+ * Package-manager override or resolution entries whose key or value does
+ * not parse in the declaration source's grammar (empty key, empty value,
+ * malformed selector, unbalanced parent matcher). The package manager may
+ * reject or ignore these at install time. Default severity is error. Wrapped in
  * [`MisconfiguredDependencyOverrideFinding`].
  */
 misconfigured_dependency_overrides?: MisconfiguredDependencyOverrideFinding[]
@@ -11022,6 +11086,10 @@ _meta?: (Meta | null)
  * distinguish "gate ran and passed" from "gate did not run" (absent).
  */
 gate?: (SecurityGate | null)
+/**
+ * Diagnostics owned by this security analysis run.
+ */
+workspace_diagnostics?: WorkspaceDiagnostic[]
 /**
  * Security candidates. Paths are project-root-relative, forward-slash.
  */
@@ -11639,6 +11707,10 @@ _meta?: (Meta | null)
  * Gate verdict, present only when `--gate <mode>` was set.
  */
 gate?: (SecurityGate | null)
+/**
+ * Diagnostics owned by the full security analysis summarized here.
+ */
+workspace_diagnostics?: WorkspaceDiagnostic[]
 summary: SecuritySummary
 }
 /**
@@ -11758,6 +11830,10 @@ export interface SecuritySurvivorsOutput {
 schema_version: SecuritySurvivorsSchemaVersion
 version: ToolVersion
 elapsed_ms: ElapsedMs
+/**
+ * Diagnostics preserved from the candidate security report.
+ */
+workspace_diagnostics?: WorkspaceDiagnostic[]
 summary: SecuritySurvivorsSummary
 /**
  * Verifier-retained candidates keyed by finding id.
@@ -11840,6 +11916,10 @@ export interface SecurityBlindSpotsOutput {
 schema_version: SecurityBlindSpotsSchemaVersion
 version: ToolVersion
 elapsed_ms: ElapsedMs
+/**
+ * Diagnostics owned by the security analysis used for this view.
+ */
+workspace_diagnostics?: WorkspaceDiagnostic[]
 summary: SecurityBlindSpotsSummary
 /**
  * Grouped unresolved callee diagnostics, derived from existing samples.
@@ -11918,6 +11998,15 @@ dupes?: (DupesReportPayload | null)
  * Health section of the combined run.
  */
 health?: (HealthReport | null)
+/**
+ * Workspace-discovery, source-discovery, and analysis-stage diagnostics
+ * for the run (issue #2366). See `CheckOutput::workspace_diagnostics` for
+ * the full contract: root-relative paths, omitted when empty. The
+ * combined envelope carries them here rather than inside a section, so a
+ * run that skips a section (`--skip check`, `--only health`,
+ * `--only dupes`) still reports every diagnostic its analyses recorded.
+ */
+workspace_diagnostics?: WorkspaceDiagnostic[]
 /**
  * Read-only follow-up commands aggregated across the combined run's
  * findings. See `CheckOutput::next_steps` for the contract.