fallow 3.37.0 → 3.38.1

package/capabilities.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "3.37.0",
+  "version": "3.38.1",
   "manifest_version": "1",
   "description": "Codebase analyzer for TypeScript/JavaScript: unused code, circular dependencies, code duplication, complexity hotspots, and architecture boundary violations",
   "global_flags": [
@@ -67,6 +67,26 @@
         "false"
       ]
     },
+    {
+      "name": "--lean",
+      "type": "bool",
+      "required": false,
+      "description": "Trim JSON for agent context: leave out empty arrays and zero dead-code summary counts, group workspace diagnostics, cap health tables, and move repeated action text to `_meta.actions`. Requires JSON output. Applies to dead-code, health and the combined report; other commands reject it. Run without `--lean` for the full diagnostic list and the complete tables",
+      "possible_values": [
+        "true",
+        "false"
+      ]
+    },
+    {
+      "name": "--full-tables",
+      "type": "bool",
+      "required": false,
+      "description": "With `--lean`, keep every row of the health tables (`hotspots`, `file_scores`, `large_functions`)",
+      "possible_values": [
+        "true",
+        "false"
+      ]
+    },
     {
       "name": "--quiet",
       "type": "bool",
@@ -1299,6 +1319,16 @@
             "false"
           ]
         },
+        {
+          "name": "--kill-matrix",
+          "type": "bool",
+          "required": false,
+          "description": "Collect all killing tests and report redundant-test candidates for individual review. Run every covering test without stopping at a failure",
+          "possible_values": [
+            "true",
+            "false"
+          ]
+        },
         {
           "name": "paths",
           "type": "string",
@@ -1342,9 +1372,30 @@
             "true",
             "false"
           ]
+        },
+        {
+          "name": "--cloud",
+          "type": "bool",
+          "required": false,
+          "description": "OPT-IN: attach Fallow Cloud production evidence for a `--file` target as the `cloud` evidence section: calls, errors, CPU and never-run branches per function. The API key is $FALLOW_API_KEY, else the key that `fallow cloud login` stored. A missing key, a plan gate or an unreachable cloud is a section status, never a failed run",
+          "possible_values": [
+            "true",
+            "false"
+          ]
+        },
+        {
+          "name": "--repo",
+          "type": "string",
+          "required": false,
+          "description": "Fallow Cloud repository for `--cloud`. Precedence: this flag > $FALLOW_REPO > the `origin` git remote"
         }
       ]
     },
+    {
+      "name": "cloud",
+      "description": "Connect this machine to Fallow Cloud",
+      "flags": []
+    },
     {
       "name": "trace",
       "description": "Trace a symbol's call chain, or the shortest import path between two modules (best-effort, syntactic; OFF the ranked path)",
@@ -1851,6 +1902,12 @@
           "required": false,
           "description": "Maximum CRAP score threshold (overrides config, default 30.0). Functions meeting or exceeding this score are reported alongside complexity findings. Pair with `--coverage` for accurate scoring"
         },
+        {
+          "name": "--max-file-lines",
+          "type": "string",
+          "required": false,
+          "description": "Maximum physical lines per file (overrides config `health.maxFileLines`, default 0 = off). A longer file is reported as a complexity finding with `exceeded: \"file_lines\"`"
+        },
         {
           "name": "--top",
           "type": "string",
@@ -4794,6 +4851,36 @@
       "license_note": null,
       "docs_url": "https://fallow.tools/docs/explanations/health/#crap-score"
     },
+    {
+      "id": "long-file",
+      "rule_id": "fallow/long-file",
+      "command": "health",
+      "category": "Health",
+      "description": "File has more lines than the file-length threshold",
+      "label": null,
+      "config_key": null,
+      "registry_index": null,
+      "aliases": [],
+      "lsp": false,
+      "filter_flag": "--complexity",
+      "result_key": null,
+      "summary_label": null,
+      "summary_docs_anchor": null,
+      "sarif_rule_ids": null,
+      "codeclimate_check_names": null,
+      "ts_alias": null,
+      "counts_in_total": false,
+      "fixable": false,
+      "suppressible": true,
+      "suppress_comment": "// fallow-ignore-file complexity",
+      "default_severity": null,
+      "opt_in": null,
+      "frameworks": [],
+      "note": null,
+      "license": "free",
+      "license_note": null,
+      "docs_url": "https://fallow.tools/docs/explanations/health/#file-length"
+    },
     {
       "id": "refactoring-target",
       "rule_id": "fallow/refactoring-target",
@@ -7048,7 +7135,7 @@
     "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_TIMEOUT_SECS": "Wall clock in seconds allowed for one TypeScript semantic sidecar request (default 120; unset, 0, or a non-numeric value keeps the default). Raise it for very large TypeScript programs, where a semantic query scans the whole program.",
-    "FALLOW_TYPE_AWARE_BACKEND": "Experimental. Type-checker backend for the TypeScript semantic sidecar: typescript-go (default) or tsrs. The tsrs backend needs the exact pinned tsrs npm package where fallow-type-aware can resolve it. An unknown value makes the type-aware pass unavailable.",
+    "FALLOW_TYPE_AWARE_BACKEND": "Experimental. Type-checker backend for the TypeScript semantic sidecar: typescript-go (default) or tsrs. The tsrs backend needs a tsrs npm package in the supported range of the type-aware protocol manifest, where fallow-type-aware can resolve it. An unknown value makes the type-aware pass unavailable.",
     "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.",
     "FALLOW_AUDIT_BASE": "Pins the fallow audit comparison base ref when no --base/--changed-since is passed (e.g. upstream/main).",
     "FALLOW_AUDIT_CACHE_MAX_AGE_DAYS": "GC threshold in days for reusable audit base-snapshot caches (default 30; 0 disables the sweep).",
@@ -7060,9 +7147,10 @@
     "FALLOW_COV_BIN": "Explicit path override for the fallow-cov runtime-coverage sidecar binary.",
     "FALLOW_COV_BINARY_PATH": "Secondary explicit path override for the fallow-cov sidecar, checked after FALLOW_COV_BIN (air-gapped installs, distro-packaged sidecars, shared Docker images).",
     "FALLOW_RUNTIME_COVERAGE_SOURCE": "Set to cloud to select cloud runtime coverage in fallow coverage analyze without passing --cloud.",
-    "FALLOW_REPO": "owner/repo fallback for fallow coverage analyze --cloud when --repo is not passed (otherwise parsed from the git origin remote).",
+    "FALLOW_REPO": "owner/repo fallback for fallow coverage analyze --cloud and fallow inspect --cloud when --repo is not passed (otherwise parsed from the git origin remote).",
     "FALLOW_API_URL": "Base URL override for Fallow Cloud API calls (license refresh, trial, coverage uploads).",
-    "FALLOW_API_KEY": "Fallow Cloud bearer token for coverage upload commands, and the fallback bearer for fallow license refresh when the stored license JWT is missing or too stale.",
+    "FALLOW_API_KEY": "Fallow Cloud bearer token for coverage upload and cloud read commands (wins over the key that fallow cloud login stored), and the fallback bearer for fallow license refresh when the stored license JWT is missing or too stale.",
+    "FALLOW_CREDENTIAL_STORE": "Credential store for the key that fallow cloud login writes: auto (default: OS keychain, else ~/.config/fallow/credentials), file (credentials file only) or none (no stored key is read or written).",
     "FALLOW_CA_BUNDLE": "Path to a PEM certificate bundle for Fallow Cloud and provider HTTP calls (replaces the default WebPKI roots).",
     "FALLOW_UPDATE_CHECK": "Set to off/0/false to disable the human-TTY upgrade nudge and its background version check.",
     "FALLOW_CLAUDE_CODE_HINT": "Set to off/0/false/no/disabled to suppress the one-line Claude Code plugin hint on stderr. Fallow writes the hint only inside a Claude Code session (CLAUDECODE or CLAUDE_CODE_CHILD_SESSION), for human output without --quiet, outside CI, and when no Fallow plugin or skill is set up for the project. Default on.",

package/issue-registry.json

@@ -3161,6 +3161,36 @@
       "license_note": null,
       "docs_url": "https://fallow.tools/docs/cli/security/"
     },
+    {
+      "id": "long-file",
+      "rule_id": "fallow/long-file",
+      "command": "health",
+      "category": "Health",
+      "description": "File has more lines than the file-length threshold",
+      "label": null,
+      "config_key": null,
+      "registry_index": null,
+      "aliases": [],
+      "lsp": false,
+      "filter_flag": "--complexity",
+      "result_key": null,
+      "summary_label": null,
+      "summary_docs_anchor": null,
+      "sarif_rule_ids": null,
+      "codeclimate_check_names": null,
+      "ts_alias": null,
+      "counts_in_total": false,
+      "fixable": false,
+      "suppressible": true,
+      "suppress_comment": "// fallow-ignore-file complexity",
+      "default_severity": null,
+      "opt_in": null,
+      "frameworks": [],
+      "note": null,
+      "license": "free",
+      "license_note": null,
+      "docs_url": "https://fallow.tools/docs/explanations/health/#file-length"
+    },
     {
       "id": "mass-assignment",
       "rule_id": "security/mass-assignment",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "3.37.0",
+  "version": "3.38.1",
   "mcpName": "io.github.fallow-rs/fallow",
   "description": "Codebase intelligence for TypeScript and JavaScript: health, complexity, duplication, architecture, styling drift, and unused code from one graph. CLI, LSP, and MCP server. Zero config for over 100 frameworks.",
   "license": "MIT",
@@ -92,14 +92,14 @@
     "@tanstack/intent": "0.5.6"
   },
   "optionalDependencies": {
-    "@fallow-cli/darwin-arm64": "3.37.0",
-    "@fallow-cli/darwin-x64": "3.37.0",
-    "@fallow-cli/linux-x64-gnu": "3.37.0",
-    "@fallow-cli/linux-arm64-gnu": "3.37.0",
-    "@fallow-cli/linux-x64-musl": "3.37.0",
-    "@fallow-cli/linux-arm64-musl": "3.37.0",
-    "@fallow-cli/win32-arm64-msvc": "3.37.0",
-    "@fallow-cli/win32-x64-msvc": "3.37.0",
-    "fallow-type-aware": "3.37.0"
+    "@fallow-cli/darwin-arm64": "3.38.1",
+    "@fallow-cli/darwin-x64": "3.38.1",
+    "@fallow-cli/linux-x64-gnu": "3.38.1",
+    "@fallow-cli/linux-arm64-gnu": "3.38.1",
+    "@fallow-cli/linux-x64-musl": "3.38.1",
+    "@fallow-cli/linux-arm64-musl": "3.38.1",
+    "@fallow-cli/win32-arm64-msvc": "3.38.1",
+    "@fallow-cli/win32-x64-msvc": "3.38.1",
+    "fallow-type-aware": "3.38.1"
   }
 }

package/schema.json

@@ -179,7 +179,7 @@
       "$ref": "#/$defs/MutationConfig"
     },
     "health": {
-      "description": "Sets complexity and health thresholds for `fallow health` (also applied in combined `fallow` and `fallow audit`): `maxCyclomatic` (20), `maxCognitive` (15), `maxCrap` (30.0, findings at or above this are reported), `crapRefactorBand` (5, cyclomatic band below `maxCyclomatic` where a secondary refactor action is added), `maxUnitSize` (max function lines before a large-function finding, 60), `coverage`/`coverageRoot` (Istanbul coverage path and path-prefix strip for accurate CRAP), `ignore` globs (remove files from findings AND the health score), `thresholdOverrides` (per-file/per-function ceilings via `files`/`functions`/`maxCyclomatic`/`maxCognitive`/`maxCrap`/`maxUnitSize`/`reason`), `ownership` (`botPatterns` and `emailMode` for `--ownership`), and `suggestInlineSuppression` (true, emit `suppress-line` action hints in JSON). Raise thresholds to relax which functions are flagged, wire `coverage` for real CRAP scores, or exempt generated/test files via `ignore` (drops them from the score too) or `thresholdOverrides` (keeps them visible under a higher ceiling). The four `max*` thresholds govern findings only and never move `health_score`: its penalties use fixed calibration so grades stay comparable across projects, and `ignore` is the lever that removes files from the score.",
+      "description": "Sets complexity and health thresholds for `fallow health` (also applied in combined `fallow` and `fallow audit`): `maxCyclomatic` (20), `maxCognitive` (15), `maxCrap` (30.0, findings at or above this are reported), `crapRefactorBand` (5, cyclomatic band below `maxCyclomatic` where a secondary refactor action is added), `maxUnitSize` (max function lines before a large-function finding, 60), `maxFileLines` (max physical lines per file before a file-level finding, 0 means off), `coverage`/`coverageRoot` (Istanbul coverage path and path-prefix strip for accurate CRAP), `ignore` globs (remove files from findings AND the health score), `thresholdOverrides` (per-file/per-function ceilings via `files`/`functions`/`maxCyclomatic`/`maxCognitive`/`maxCrap`/`maxUnitSize`/`maxFileLines`/`reason`), `ownership` (`botPatterns` and `emailMode` for `--ownership`), and `suggestInlineSuppression` (true, emit `suppress-line` action hints in JSON). Raise thresholds to relax which functions are flagged, wire `coverage` for real CRAP scores, or exempt generated/test files via `ignore` (drops them from the score too) or `thresholdOverrides` (keeps them visible under a higher ceiling). The `max*` thresholds govern findings only and never move `health_score`: its penalties use fixed calibration so grades stay comparable across projects, and `ignore` is the lever that removes files from the score.",
       "$ref": "#/$defs/HealthConfig",
       "default": {
         "maxCyclomatic": 20,
@@ -253,6 +253,7 @@
         "complexity-cyclomatic": "error",
         "complexity-cognitive": "error",
         "complexity-crap": "error",
+        "complexity-file-lines": "error",
         "unresolved-imports": "error",
         "unlisted-dependencies": "error",
         "duplicate-exports": "error",
@@ -1309,6 +1310,12 @@
           "minimum": 0,
           "default": 60
         },
+        "maxFileLines": {
+          "description": "Maximum file length in physical lines before the file is reported as a\ncomplexity finding with `exceeded: \"file_lines\"` (default: `0`, off).\nEvery line counts, also blank lines and comment lines. A final newline\ndoes not add a line. Set a limit such as `500` to enable the check, and\nraise it per file via `thresholdOverrides[].maxFileLines`. The\n`complexity-file-lines` rule decides if a finding fails the run. In\n`fallow audit`, a long file that did not grow stays inherited. Older\nfallow versions reject this key as unknown, so pair it with\n`minimumVersion`.",
+          "type": "integer",
+          "format": "uint32",
+          "minimum": 0
+        },
         "coverage": {
           "description": "Path to Istanbul coverage data (coverage-final.json) or raw V8 coverage\n(a `NODE_V8_COVERAGE` directory or one V8 JSON file) for accurate\nper-function CRAP scores. 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`,\n`fallow viz`, and the MCP `audit` / `check_health` tools.",
           "type": [
@@ -1443,6 +1450,15 @@
           "format": "uint32",
           "minimum": 0
         },
+        "maxFileLines": {
+          "description": "Local file-length ceiling in physical lines. `0` turns the file-length\ncheck off for the matching files. The ceiling applies to whole files,\nso an entry that sets it must leave `functions` empty.",
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint32",
+          "minimum": 0
+        },
         "reason": {
           "description": "Human-readable rationale for the exception.",
           "type": [
@@ -1761,6 +1777,11 @@
           "$ref": "#/$defs/Severity",
           "default": "error"
         },
+        "complexity-file-lines": {
+          "description": "A file above the file-length ceiling (`health.maxFileLines` or a\n`thresholdOverrides` entry). The threshold decides if the finding\nexists, and it is off by default; this rule decides if it fails the\nrun. Defaults to `error`.",
+          "$ref": "#/$defs/Severity",
+          "default": "error"
+        },
         "unresolved-imports": {
           "description": "An import specifier that resolves to no file or package. Defaults to\n`error`.",
           "$ref": "#/$defs/Severity",
@@ -2774,6 +2795,17 @@
             }
           ]
         },
+        "complexity-file-lines": {
+          "description": "Optional override for [`RulesConfig::complexity_file_lines`].",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/Severity"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
         "unresolved-imports": {
           "description": "Optional override for [`RulesConfig::unresolved_imports`].",
           "anyOf": [

package/skills/fallow/SKILL.md

@@ -67,7 +67,7 @@ Offer setup after showing the findings from a human-requested analysis, only whe
 
 Offer these choices: guard commits and PRs, baseline the existing backlog and clean by category, add AGENTS.md guidance, or keep as-is. Mutate only after consent. On decline, run `fallow init --decline --quiet` and stay silent for this project.
 
-For guards, inspect `fallow hooks status --format json --quiet`, then use `fallow hooks install --target agent` and `fallow hooks install --target git`. For large backlogs, pair the gate with `--save-baseline` and new-only guidance.
+For complete agent onboarding, use the `fallow-setup` skill: preview `fallow agent install --dry-run`, apply the approved setup, then run `fallow agent status --format json --quiet`. Report runtime blockers and pending harness trust before calling the setup ready. For an explicit guard-only request, inspect `fallow hooks status --format json --quiet` and install the requested agent or Git hook. For large backlogs, pair the gate with `--save-baseline` and new-only guidance.
 
 Offer `fallow impact enable` for local value tracking. Impact is separate from telemetry. Also offer it once on an already-configured project when `fallow impact status --format json` has `enabled: false` and `explicit_decision: false`. Record a decline with `fallow impact disable --quiet`.
 

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

@@ -54,7 +54,8 @@ Every fallow command with its purpose and key flags. The table is regenerated fr
 | `doctor` | Diagnose project readiness without analysis or mutation |  |
 | `similar-code` | Find semantically similar functions with a pinned local model (opt-in) | `--threshold`, `--min-lines`, `--top`, `--file` |
 | `mutation` | Measure how well the tests detect changes in the code (opt-in) | `--all`, `--plan`, `--max-mutants`, `--time-budget`, `--concurrency`, `--runtime`, `--runner-config`, `--allow-dirty`, `--allow-side-effects` |
-| `inspect` | Compose one evidence bundle for a file or exported symbol | `--file <path>`, `--symbol <file>:<export>` |
+| `inspect` | Compose one evidence bundle for a file or exported symbol, with optional Fallow Cloud production data | `--file <path>`, `--symbol <file>:<export>`, `--cloud`, `--repo <owner/repo>` |
+| `cloud` | Log in to Fallow Cloud with the device flow and store a read-only API key (login, logout) | `login --machine-name <name>`, `login --api-url <url>`, `logout` |
 | `trace` | Trace a symbol's call chain, or with `--path` the shortest import path between two modules (best-effort, syntactic; OFF the ranked path) | `symbol`, `--path <FROM> <TO>`, `--eager-only`, `--callers`, `--callees`, `--depth` |
 | `trace-error` | Resolve a runtime stack trace's frames to the definitions they name (best-effort, syntactic; OFF the ranked path) | `trace_file` |
 | `fix` | Auto-remove unused exports/deps | `--dry-run`, `--yes` (required in non-TTY) |
@@ -74,7 +75,7 @@ Every fallow command with its purpose and key flags. The table is regenerated fr
 | `list` | Inspect project structure | `--files`, `--entry-points`, `--plugins`, `--boundaries`, `--workspaces`, `--entry-weight` |
 | `workspaces` | Inspect monorepo workspaces + discovery diagnostics (shorthand for `list --workspaces`) | (no flags) |
 | `dupes` | Code duplication detection | `--mode`, `--near`, `--threshold`, `--top`, `--changed-since`, `--workspace`, `--changed-workspaces`, `--skip-local`, `--cross-language`, `--ignore-imports`, `--explain-skipped`, `--fail-on-regression`, `--tolerance`, `--regression-baseline`, `--save-regression-baseline` |
-| `health` | Function complexity analysis (also covers component templates as synthetic `<template>` findings: Angular external `.html` files via `templateUrl` AND inline `@Component({ template: \`...\` })` literals, plus Vue, Svelte and Astro single-file components; suppress an Angular external template with `<!-- fallow-ignore-file complexity -->` at the top of the `.html` file, an Angular inline template with `// fallow-ignore-next-line complexity` directly above the `@Component` decorator, and a `.svelte` / `.vue` / `.astro` template with `<!-- fallow-ignore-next-line complexity -->` on the line immediately above the reported line) | `--complexity`, `--max-cyclomatic`, `--max-cognitive`, `--max-crap`, `--top`, `--sort`, `--file-scores`, `--hotspots`, `--ownership`, `--ownership-emails`, `--targets`, `--effort`, `--score`, `--min-score`, `--since`, `--min-commits`, `--save-snapshot`, `--trend`, `--coverage-gaps`, `--coverage`, `--coverage-root`, `--runtime-coverage`, `--min-invocations-hot`, `--min-observation-volume`, `--low-traffic-threshold`, `--css`, `--complexity-breakdown`, `--min-severity`, `--report-only`, `--workspace`, `--changed-workspaces`, `--baseline`, `--save-baseline` |
+| `health` | Function complexity analysis (also covers component templates as synthetic `<template>` findings: Angular external `.html` files via `templateUrl` AND inline `@Component({ template: \`...\` })` literals, plus Vue, Svelte and Astro single-file components; suppress an Angular external template with `<!-- fallow-ignore-file complexity -->` at the top of the `.html` file, an Angular inline template with `// fallow-ignore-next-line complexity` directly above the `@Component` decorator, and a `.svelte` / `.vue` / `.astro` template with `<!-- fallow-ignore-next-line complexity -->` on the line immediately above the reported line) | `--complexity`, `--max-cyclomatic`, `--max-cognitive`, `--max-crap`, `--max-file-lines`, `--top`, `--sort`, `--file-scores`, `--hotspots`, `--ownership`, `--ownership-emails`, `--targets`, `--effort`, `--score`, `--min-score`, `--since`, `--min-commits`, `--save-snapshot`, `--trend`, `--coverage-gaps`, `--coverage`, `--coverage-root`, `--runtime-coverage`, `--min-invocations-hot`, `--min-observation-volume`, `--low-traffic-threshold`, `--css`, `--complexity-breakdown`, `--min-severity`, `--report-only`, `--workspace`, `--changed-workspaces`, `--baseline`, `--save-baseline` |
 | `flags` | Detect feature flag patterns (env vars, SDK calls, config objects) | `--top`, `--retirement`, `--reason`, `--min-age`, `--flag-state`, `--max-flag-age` |
 | `suppressions` | List active fallow-ignore suppression markers (read-only inventory) | `--file` |
 | `explain` | Explain one issue type without running analysis | `<issue-type>`, `--format json` |
@@ -526,7 +527,7 @@ Human output groups paths under "Shared with your team (commit these)" and "Loca
 {
   "kind": "agent-install",
   "schema_version": 1,
-  "fallow_version": "3.37.0",
+  "fallow_version": "3.38.1",
   "root": "/abs/path",
   "mode": "install",
   "dry_run": false,
@@ -605,6 +606,7 @@ Angular templates contribute synthetic `<template>` complexity findings whenever
 | `--max-cyclomatic` | `string` | - | Fail if any function exceeds this cyclomatic complexity |
 | `--max-cognitive` | `string` | - | Fail if any function exceeds this cognitive complexity |
 | `--max-crap` | `string` | - | Fail if any function has CRAP score >= threshold. CRAP combines complexity with coverage (`CC^2 * (1 - cov/100)^3 + CC`). Pair with `--coverage` for accurate per-function CRAP; without coverage data fallow estimates coverage from the module graph. |
+| `--max-file-lines` | `string` | - | Maximum physical lines per file (overrides config `health.maxFileLines`, default 0 = off). A longer file is reported as a complexity finding with `exceeded: "file_lines"` |
 | `--top` | `string` | - | Only show the top N most complex functions (and file scores/hotspots/targets) |
 | `--sort` | `severity\|cyclomatic\|cognitive\|lines` | `cyclomatic` | Sort order for complexity findings |
 | `--complexity` | `bool` | `false` | Show only function complexity findings. When no section flags are set, all sections are shown by default. |
@@ -737,7 +739,7 @@ fallow health --format json --quiet --trend
 {
   "kind": "health",
   "schema_version": 7,
-  "version": "3.37.0",
+  "version": "3.38.1",
   "elapsed_ms": 32,
   "summary": {
     "files_analyzed": 482,
@@ -1212,7 +1214,7 @@ fallow audit \
 {
   "kind": "audit",
   "schema_version": 7,
-  "version": "3.37.0",
+  "version": "3.38.1",
   "command": "audit",
   "verdict": "fail",
   "changed_files_count": 12,
@@ -1300,7 +1302,7 @@ fallow flags --format json --quiet --workspace my-package
 ```json
 {
   "schema_version": 7,
-  "version": "3.37.0",
+  "version": "3.38.1",
   "elapsed_ms": 116,
   "feature_flags": [],
   "total_flags": 0
@@ -1401,7 +1403,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "3.37.0",
+  "version": "3.38.1",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -1430,7 +1432,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "3.37.0",
+  "version": "3.38.1",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -1504,6 +1506,8 @@ Compose one evidence bundle before editing a file or exported symbol. This is th
 fallow inspect --file src/api.ts --format json --quiet
 fallow inspect --symbol src/api.ts:fetchUser --format json --quiet
 fallow inspect --file src/api.ts --churn --format json --quiet
+fallow inspect --file src/api.ts --cloud --format json --quiet
+fallow inspect --file src/api.ts --cloud --format compact
 ```
 
 ### Target Flags
@@ -1513,6 +1517,12 @@ fallow inspect --file src/api.ts --churn --format json --quiet
 | `--file <PATH>` | Inspect one project-relative file |
 | `--symbol <FILE:EXPORT>` | Inspect one exported symbol. Supporting dead-code, duplication, complexity, and security evidence is file-scoped in the first version |
 | `--churn` | Add target-level git churn evidence. Off by default; missing git history is reported as `unavailable` |
+| `--cloud` | Add the `cloud` evidence section for a `--file` target: Fallow Cloud production data per local function (state, calls, error groups, CPU ms per hour, never-run branches). Off by default. Key: `$FALLOW_API_KEY`, else the key that `fallow cloud login` stored. The section `status` is `ok`, `no_key`, `plan_required`, `unavailable` or `untracked`; a status other than `ok` never fails the run. Requires fallow 3.38.0 or later |
+| `--repo <OWNER/REPO>` | Fallow Cloud repository for `--cloud`. Precedence: this flag > `$FALLOW_REPO` > the `origin` git remote |
+
+`--format compact` for `inspect` requires fallow 3.38.0 or later. It prints plain text of about 1 KB, one line per item and no colors: a `fallow <path>` header, `finding <kind> <path:line> <text>` lines, `prod <name:line> <text>` lines (functions with errors first, then `never_called`, then local functions without production data, then the rest), a `cloud <status>: <text>` line for a status other than `ok`, and `truncated <n> more` when the byte cap cuts lines.
+
+Local functions pair with deployed functions by `stable_id` first, then by the name plus the ordinal among the same-name functions of the file. A local function without a pair goes to `unpaired_local` with the note `no production data (new or moved since deploy)`. A `null` count means "not measured", never zero.
 
 Common global flags: `--format`, `--quiet`, `--root`, `--config`, `--workspace`, `--production`, `--no-cache`, `--threads`.
 
@@ -1696,6 +1706,27 @@ Pack files can also reference the published schema directly: `"$schema": "https:
 
 ---
 
+## `cloud`: Log In to Fallow Cloud
+
+Requires fallow 3.38.0 or later. Connect this machine to Fallow Cloud without copying a key. `login` runs the device flow: it prints a code and a URL, and after a user approves the code in the dashboard the cloud creates a read-only API key (`fallow_read_k1_`) for that user, organization and machine. The CLI stores the key and never prints it. Agents must not run `login`; only the user may approve it.
+
+```bash
+fallow cloud login
+fallow cloud login --machine-name build-box
+fallow cloud logout
+```
+
+| Flag | Description |
+|------|-------------|
+| `--machine-name <NAME>` | Name of the machine on the key (`login` only). Default: the host name |
+| `--api-url <URL>` | Fallow Cloud API base URL. Default: `$FALLOW_API_URL`, else `https://api.fallow.cloud` |
+
+Storage: the OS keychain (service `fallow-cloud`, account = the API base URL; `security` on macOS, `secret-tool` on Linux), else `~/.config/fallow/credentials` (mode 0600). `FALLOW_CREDENTIAL_STORE=file` skips the keychain; `FALLOW_CREDENTIAL_STORE=none` turns stored keys off. `logout` removes the stored key; the key stays valid until you revoke it in Settings.
+
+Every command that reads a cloud key uses one order: `--api-key` > `$FALLOW_API_KEY` > the keychain > the credentials file.
+
+---
+
 ## `license`: Manage the Fallow Cloud License
 
 Manage the local JWT used to unlock continuous/cloud runtime monitoring. Single-capture local runtime analysis does not require a license. Verification is fully offline against an Ed25519 public key compiled into the binary. Only `--trial` and `refresh` hit the network (`api.fallow.cloud`, 5s connect / 10s total timeout).
@@ -2014,6 +2045,8 @@ Available on all commands:
 | `--allow-remote-extends` | `bool` | `false` | Allow trusted config files to extend HTTPS URLs |
 | `-f, --format` | `human\|json\|sarif\|compact\|markdown\|codeclimate\|pr-comment-github\|pr-comment-gitlab\|review-github\|review-gitlab\|badge\|github-annotations\|github-summary` | `human` | Output format (alias: --output) |
 | `--pretty` | `bool` | `false` | Indent JSON output for manual inspection. Requires the final output format to be JSON |
+| `--lean` | `bool` | `false` | Trim JSON for agent context: leave out empty arrays and zero dead-code summary counts, group workspace diagnostics, cap health tables, and move repeated action text to `_meta.actions`. Requires JSON output. Applies to dead-code, health and the combined report; other commands reject it. Run without `--lean` for the full diagnostic list and the complete tables |
+| `--full-tables` | `bool` | `false` | With `--lean`, keep every row of the health tables (`hotspots`, `file_scores`, `large_functions`) |
 | `-q, --quiet` | `bool` | `false` | Suppress progress output |
 | `--no-cache` | `bool` | `false` | Disable incremental caching |
 | `--threads` | `string` | - | Number of parser threads |
@@ -2183,6 +2216,40 @@ Set `FALLOW_FORMAT=json` and `FALLOW_QUIET=1` in your agent environment to avoid
 
 ---
 
+## `mutation --kill-matrix`: Redundant test evidence
+
+```bash
+fallow mutation --all --kill-matrix --format json --quiet
+```
+
+This opt-in mode runs all covering tests with bail disabled. It can increase execution time.
+Read the matrix evidence status before you review candidates. Normal mode reports `kill-matrix-disabled` and no candidates.
+Incomplete evidence also produces no candidates.
+
+`kills` and `unique_kills` are arrays of mutant IDs.
+Individual subsumers cover a candidate's full kill set. Other tests can also cover that set collectively.
+Review each candidate separately, including equal kill sets. Removing equal candidates together can remove their shared protection.
+A candidate does not prove safe removal. Baseline-failing tests cannot become candidates or subsumers.
+
+Tests with runtime coverage and no observed kills appear separately. Zero kills do not prove that a test has no assertions.
+Sole-file notes use observed instrumented-file coverage. Public-export notes use static test-file reach, without per-test export coverage claims.
+
+The `mutation` and `mutation-inspect` JSON envelopes use schema version `"2"`. The `mutation-plan` envelope and verdict document keep schema version `"1"`.
+
+The `kill_matrix` object has these fields:
+
+| Field | Meaning |
+|---|---|
+| `status` | `complete`, `incomplete`, or `unavailable`, separate from mutation completion. |
+| `reasons` | Evidence limitations, such as `kill-matrix-disabled`, `incomplete-mutant-results`, `baseline-failure`, `partial-mutation-run`, or `missing-test-file-metadata`. |
+| `tests` | Entries with `test_id`, `file`, `kills`, `unique_kills`, `subsuming_tests`, and `notes`. |
+| `candidates` | Test IDs whose observed kill sets other tests cover. |
+| `coverage_without_kills` | Test IDs with runtime coverage and no observed kills. |
+
+Each mutant and attempt records `killing_tests` and `kill_matrix_complete`. The existing `killed_by` field keeps the first observed killer. Outside matrix mode, `killing_tests` is empty.
+
+Matrix mode does not add the other tests of the covering test files to the retry of a survivor. A survivor that normal mode kills in that retry can stay `survived` in matrix mode, so the two modes can give different scores.
+
 ## `ci`: Provider-Aware Review Automation
 
 `fallow ci reconcile-review` reads a typed review envelope (`--format review-github` / `review-gitlab`), looks up existing fingerprints on the PR/MR, and resolves stale review threads when their finding is no longer present in the new envelope. Posts an idempotent "Resolved in `<sha>`" follow-up comment per stale finding (skipped if a marker for the same fingerprint at the current SHA already exists).
@@ -2245,7 +2312,7 @@ The HTTP layer mirrors the bash `gh_api_retry` / `curl_retry` helpers: `FALLOW_A
 {
   "kind": "dead-code",
   "schema_version": 7,
-  "version": "3.37.0",
+  "version": "3.38.1",
   "elapsed_ms": 45,
   "total_issues": 12,
   "entry_points": {
@@ -2405,7 +2472,7 @@ When `--baseline` is used in combined output, the JSON includes a `baseline_delt
 {
   "kind": "dupes",
   "schema_version": 7,
-  "version": "3.37.0",
+  "version": "3.38.1",
   "elapsed_ms": 82,
   "total_clones": 15,
   "total_lines_duplicated": 230,
@@ -2449,11 +2516,11 @@ When running `fallow` with no subcommand (all analyses), the JSON output combine
 {
   "kind": "combined",
   "schema_version": 7,
-  "version": "3.37.0",
+  "version": "3.38.1",
   "elapsed_ms": 159,
   "check": {
     "schema_version": 7,
-    "version": "3.37.0",
+    "version": "3.38.1",
     "elapsed_ms": 45,
     "total_issues": 12,
     "unused_files": [],

package/skills/fallow/references/issue-types.md

@@ -67,6 +67,7 @@ The `generated:issue-types` table below is regenerated from `fallow schema` by s
 | `high-cognitive-complexity` | `--complexity` | - | `// fallow-ignore-next-line complexity` | Function has high cognitive complexity |
 | `high-complexity` | `--complexity` | - | `// fallow-ignore-next-line complexity` | Function exceeds both complexity thresholds |
 | `high-crap-score` | `--complexity` | - | `// fallow-ignore-next-line complexity` | Function has a high CRAP score (complexity combined with low coverage) |
+| `long-file` | `--complexity` | - | `// fallow-ignore-file complexity` | File has more lines than the file-length threshold |
 | `refactoring-target` | `--targets` | - | - | File identified as a high-priority refactoring candidate |
 | `css-token-drift` | - | - | `// fallow-ignore-next-line css-token-drift` | CSS or CSS-in-JS hardcoded styling value bypasses the design token system |
 | `css-duplicate-block` | - | - | `// fallow-ignore-next-line css-duplicate-block` | CSS or CSS-in-JS declaration block is duplicated across rules |

package/skills/fallow/references/mcp.md

@@ -33,7 +33,7 @@ When using fallow via MCP (`fallow-mcp`), the following tools are available:
 | `get_cloud_review_packet` | runtime-coverage | freemium | `fallow coverage review-packet --repo <owner/repo> --file <path> --format json --quiet` | `repo`, `files`, `functions`, `period_days`, `project_id` | Production facts of a few changed files or functions, read from fallow cloud without the full runtime-context pull |
 | `get_cloud_deployment_changes` | runtime-coverage | freemium | `fallow coverage deployment-changes --repo <owner/repo> --sha <sha> --format json --quiet` | `repo`, `sha`, `base`, `change` | How production behavior changed between two deployments, read from the fallow cloud change report |
 | `get_token_blast_radius` | analysis | free | `fallow health --css --format json --quiet` | - | Design-token blast radius for Tailwind v4 @theme tokens and CSS-in-JS token definitions (StyleX, vanilla-extract, PandaCSS): per token, a consumer_count (static lower bound) and a capped located consumers[] sample tagged theme-var/css-var/utility/apply (Tailwind), js-member (member access), or js-call (StyleX theme-group and Panda token calls); descriptive context for sizing a token change, never a deletion gate |
-| `audit` | analysis | free | `fallow audit --format json --quiet` | `gate`, `base`, `skip`, `css_deep`, `max_crap`, `coverage`, `runtime_coverage` | Combined dead-code + complexity + duplication + styling + diff risk for changed files, returns verdict. The diff-risk rules (`weakened-tests`, `added-suppression`, `test-only-branch`, and the opt-in `diverged-clone-sibling` and `added-dependency`, both off by default) report facts about the change in `diff_risk.findings`. Styling analytics are enabled by default; CSS and CSS-in-JS evidence can add `styling_findings`, `css_analytics`, and `styling_health` under the health sub-result. Set `gate` to `"new-only"` or `"all"`. Set `css_deep: false` to skip project-wide styling reachability while keeping local styling checks, or `css_deep: true` to force it back on when config disables it. Optional `runtime_coverage` (V8 dir / V8 JSON / Istanbul JSON) folds runtime findings into the same call; `min_invocations_hot` tunes the hot-path threshold (default 100). Runtime evidence appears under the audit `complexity` sub-result, including `coverage_intelligence` when combined evidence yields actionable recommendations. |
+| `audit` | analysis | free | `fallow audit --format json --quiet` | `gate`, `base`, `skip`, `css_deep`, `max_crap`, `coverage`, `runtime_coverage` | Combined dead-code + complexity + duplication + styling + diff risk for changed files, returns verdict. The diff-risk rules (`weakened-tests`, `added-suppression`, `test-only-branch`, and the opt-in `diverged-clone-sibling` and `added-dependency`, both off by default) report facts about the change in `diff_risk.findings`. Styling analytics are enabled by default; CSS and CSS-in-JS evidence can add `styling_findings`, `css_analytics`, and `styling_health` under the audit `complexity` sub-result. Set `gate` to `"new-only"` or `"all"`. Set `css_deep: false` to skip project-wide styling reachability while keeping local styling checks, or `css_deep: true` to force it back on when config disables it. Optional `runtime_coverage` (V8 dir / V8 JSON / Istanbul JSON) folds runtime findings into the same call; `min_invocations_hot` tunes the hot-path threshold (default 100). Runtime evidence appears under the audit `complexity` sub-result, including `coverage_intelligence` when combined evidence yields actionable recommendations. |
 | `decision_surface` | analysis | free | `fallow decision-surface --format json --quiet` | `base`, `max_decisions`, `workspace` | Surface the few consequential structural decisions a change embeds (coupling, public API, dependency), each as a judgment question with the routed expert; ranked, capped, and signal_id-anchored |
 | `fallow_explain` | introspection | free | `fallow explain <issue-type> --format json --quiet` | `issue_type` | Explain one issue type without running analysis. Required `issue_type`; returns rationale, examples, fix guidance, and docs URL |
 | `fix_preview` | fix | free | `fallow fix --dry-run --format json --quiet` | `no_create_config` | Dry-run auto-fix preview |
@@ -119,7 +119,7 @@ Use these reads when the project sends production coverage to Fallow Cloud. The
 
 - `hit_count`: the production call count. Rank hot functions by it, not by `prod_hit_count`, which counts tagged traffic only.
 - `tracking_state`: `called`, `never_called`, or `untracked` in the current deployment.
-- `covered_by_test`: `true` or `null`. `null` means no test evidence, not "no test". A hot function with `covered_by_test: null` is a high-risk edit.
+- `covered_by_test`: `true`, `false`, or `null`. `true` means a test or CI run called the function. `false` means a test or CI run tracked the function and never called it. `null` means no test evidence, not "no test". A hot function with `covered_by_test: false` or `null` is a high-risk edit.
 - `blast_radius.caller_count` and `blast_radius.caller_sites`: callers when the data exists; `null` is unknown, not zero.
 
 An entry in `not_found` has no cloud data. Absence is not evidence that the code is cold.
@@ -149,7 +149,7 @@ Most tools accept `root`, `config`, `no_cache`, and `threads` params. Exceptions
 
 Every dead-code, health, and duplication finding in JSON responses includes a structured `actions` array for programmatic fixes or suppression.
 
-`health.thresholdOverrides[]` lets projects keep known legacy functions visible as configured local ceilings instead of hiding them with suppressions. Each entry has `files` globs, optional exact `functions`, one or more of `maxCyclomatic`, `maxCognitive`, `maxCrap`, or `maxUnitSize`, and optional `reason`. Health JSON may include top-level `threshold_overrides[]` entries with `active`, `stale`, `insufficient`, or `no_match` status, and complexity findings that use an override carry `effective_thresholds` plus `threshold_source: "override"`. Each entry also names its `dimension` (`complexity` or `crap`), so one configured override yields one entry per dimension it participates in: group on `override_index` to count configured overrides. `insufficient` means the raised ceiling is still exceeded. An entry's `outstanding[]` lists every dimension the matched unit still breaches after the override applied, which is how an `active` override can sit next to a surviving finding.
+`health.thresholdOverrides[]` lets projects keep known legacy functions visible as configured local ceilings instead of hiding them with suppressions. Each entry has `files` globs, optional exact `functions`, one or more of `maxCyclomatic`, `maxCognitive`, `maxCrap`, `maxUnitSize`, or `maxFileLines`, and optional `reason`. An entry that sets `maxFileLines` must leave `functions` empty, because the ceiling applies to whole files. Health JSON may include top-level `threshold_overrides[]` entries with `active`, `stale`, `insufficient`, or `no_match` status, and complexity findings that use an override carry `effective_thresholds` plus `threshold_source: "override"`. Each entry also names its `dimension` (`complexity` or `crap`), so one configured override yields one entry per dimension it participates in: group on `override_index` to count configured overrides. `insufficient` means the raised ceiling is still exceeded. An entry's `outstanding[]` lists every dimension the matched unit still breaches after the override applied, which is how an `active` override can sit next to a surviving finding.
 
 `dead-code`, `health`, `dupes`, bare `fallow`, and `audit` JSON output may include a top-level `next_steps` array of read-only follow-up commands computed from the run's findings. Each entry is `{ id, command, reason }`. The `command` is runnable as-is (never a placeholder, never `fix` or any other mutating command); the stable kebab-case `id` (`setup`, `impact-report`, `trace-unused-export`, `trace-deprecated-export`, `trace-clone`, `complexity-breakdown`, `scope-workspaces`, `audit-changed`) maps to a verification step to run before acting, for example tracing an export before deleting it.
 

package/skills/fallow/references/patterns.md

@@ -786,7 +786,7 @@ Behavior you can rely on:
 - The hook process can start in a directory that is not the session directory, for example in the main checkout when the session works in a nested git worktree. The script reads the session directory from the `cwd` field of the hook input and finds the audit root from it with the same walk. When the walk finds no script, for example with the user-scope script in `$HOME`, the audit root is the directory of the hook process when it is in the git work tree of the session. Else it is the git top level of the session directory, or the session directory outside a git repository. The audit root is never `$HOME`. The script compares physical paths, so a symlink does not change the walk. When the hook input has no usable `cwd`, the audit runs in the directory of the hook process.
 - A `git commit` or `git push` can name another work tree. The script audits only that target when the command has the strict form `[cd <dir> &&] git [-C <dir>]... commit|push [<option or name>]...` and git reports another work tree for the target (`git rev-parse --show-toplevel --absolute-git-dir` gives a different top level and a different git directory than for the session directory). For a push, the common git directory must differ too: linked worktrees share refs, so a push from another linked worktree of the session repository audits the session tree and the target. The one exception is a push that cannot send the session branch: the options are only `-u`, `-q`, `--set-upstream`, `--force-with-lease` and `--force-if-includes`, `git rev-parse --symbolic-full-name` gives the checked-out branch of the target for each refspec source, that branch is not the session branch, and a push without a refspec has `push.default` unset or `simple`, `current`, `upstream` or `nothing` and no remote `push` or `mirror` setting. That push audits only the target. A git error during this check keeps the session audit. A target in the same work tree keeps the session audit, because `git commit` commits the whole index. Each word in the strict form must be inert: a `-C` directory resolves physically as in git, a `cd` directory starts with `/`, `./` or `../`, a double-quoted word holds no `$`, backquote or backslash, and only a short list of options such as `-m`, `--amend`, `-S` and `-u` is allowed. Any other command audits the session tree as before, plus each directory that it names in another work tree. The gate blocks when one audit fails.
 - Runs only when the intercepted command is a `git commit` or `git push`, including invocations that pass git-level options before the subcommand (`git -c user.name=x commit`, `git --no-pager commit`, `git -C dir push`, `git --git-dir=/x push`); anything else exits 0. Set `FALLOW_GATE_DEBUG=1` to log skipped commands to stderr.
-- Resolves `fallow` from PATH first, then `npx --no-install fallow` as a fallback. Skips with a stderr notice if neither is available or if `jq` is missing.
+- Prefers a native Fallow JSON reader discovered from PATH, the process directory or the script's project root; jq remains a compatibility fallback. Audit runner lookup tries PATH, project-local `node_modules/.bin/fallow`, Yarn Plug'n'Play, then `npx --no-install fallow`. A missing JSON reader or audit runner causes a stderr skip notice. Check `fallow agent status --format json --quiet` after setup for missing or unverified runtimes. Approve project trust and the hook in the harness before relying on the gate.
 - Enforces a version floor via `FALLOW_GATE_MIN_VERSION`. The installed gate script holds the default floor (currently `2.85.0`). Fallow maintainers raise that default by hand; `fallow hooks install` does not set it to the installed version. Binaries below the floor are blocked with an upgrade hint. Set the env var to the empty string to disable the check.
 - Runs `fallow audit --format json --quiet --explain --gate-marker agent`. On verdict=`fail`, it writes a short block message to stderr: the line `fallow-gate: blocked by fallow <version> at <binary>`, the verdict, one line for each finding that caused the block (`<kind> <path>:<line> <name>`, at most 50 lines), and the path of the full JSON report. Under the default `gate = "new-only"` the listed findings are the ones with `introduced: true`; under `gate = "all"` they are all findings that are not warnings. The full report goes to `.fallow/gate-report.json` in the audited tree, or to `FALLOW_GATE_REPORT` when set (a relative path resolves against the audited tree). Set `FALLOW_GATE_OUTPUT=json` to write the full JSON envelope to stderr instead, preceded by `fallow-gate: blocked by fallow <version> at <binary>` so the responsible binary is always identifiable. The gate marker lets local Impact record blocked-then-cleared agent gate events when Impact is enabled.
 - On runtime error (`{"error": true, ...}`) or unexpected non-zero exit, fails open with a one-line stderr notice; warn verdicts pass through silently.

package/types/output-contract.d.ts

@@ -24,7 +24,7 @@
 
 
 /**
- * Schemas for the JSON output of fallow commands. Object-shaped envelopes covered by the `FallowOutput` contract carry a top-level `kind` discriminator. Current kind values: `audit`, `explain`, `inspect_target`, `trace`, `trace-error`, `review-envelope`, `review-reconcile`, `coverage-setup`, `coverage-analyze`, `list-boundaries`, `list-workspaces`, `health`, `dupes`, `dead-code-grouped`, `architecture-grouped`, `impact`, `impact-cross-repo`, `security`, `security-survivors`, `security-blind-spots`, `dead-code`, `architecture`, `combined`, `feature-flags`, `audit-brief`, `decision-surface`, `review-walkthrough-guide`, `review-walkthrough-validation`, `suppression-inventory`, `doctor`, `type-aware-status`, `similar-code`, `similar-code-inspect`, `similar-code-review`, `similar-code-status`, `similar-code-cache-clear`, `mutation`, `mutation-plan`, `mutation-inspect`. Consumers should branch on `kind` instead of probing for unique field presence. `CodeClimateOutput` is a bare JSON array (per the Code Climate / GitLab Code Quality spec) and stays a sibling root branch discriminated by checking whether the document root is an array. `ErrorOutput` is the `--format json` failure document, emitted on stdout with a non-zero exit; it carries no `kind` and is discriminated by the `error: true` field.
+ * Schemas for the JSON output of fallow commands. Object-shaped envelopes covered by the `FallowOutput` contract carry a top-level `kind` discriminator. Current kind values: `audit`, `explain`, `inspect_target`, `trace`, `trace-error`, `review-envelope`, `review-reconcile`, `coverage-setup`, `coverage-analyze`, `list-boundaries`, `list-workspaces`, `health`, `dupes`, `dead-code-grouped`, `architecture-grouped`, `impact`, `impact-cross-repo`, `security`, `security-survivors`, `security-blind-spots`, `dead-code`, `architecture`, `combined`, `feature-flags`, `audit-brief`, `decision-surface`, `review-walkthrough-guide`, `review-walkthrough-validation`, `suppression-inventory`, `doctor`, `type-aware-status`, `similar-code`, `similar-code-inspect`, `similar-code-review`, `similar-code-status`, `similar-code-cache-clear`, `mutation`, `mutation-plan`, `mutation-inspect`. Consumers should branch on `kind` instead of probing for unique field presence. `CodeClimateOutput` is a bare JSON array (per the Code Climate / GitLab Code Quality spec) and stays a sibling root branch discriminated by checking whether the document root is an array. `ErrorOutput` is the `--format json` failure document, emitted on stdout with a non-zero exit; it carries no `kind` and is discriminated by the `error: true` field. A `--lean` document is not a root branch: it validates against `LeanOutput`.
  */
 export type FallowJsonOutput = (FallowOutput | CodeClimateOutput | ErrorOutput)
 /**
@@ -889,7 +889,7 @@ export type CloneFamilyActionType = ("extract-shared" | "apply-suggestion" | "su
 /**
  * Which complexity threshold was exceeded.
  */
-export type ExceededThreshold = ("cyclomatic" | "cognitive" | "both" | "crap" | "cyclomatic_crap" | "cognitive_crap" | "all")
+export type ExceededThreshold = ("cyclomatic" | "cognitive" | "both" | "crap" | "cyclomatic_crap" | "cognitive_crap" | "all" | "file_lines")
 /**
  * Severity tier indicating how far a function exceeds complexity thresholds.
  *
@@ -937,7 +937,7 @@ export type ThresholdSource = "override"
  * BOTH `increase-coverage` AND `refactor-function`, plus the trailing
  * `suppress-line`.
  */
-export type HealthFindingActionType = ("refactor-function" | "add-tests" | "increase-coverage" | "suppress-file" | "suppress-line")
+export type HealthFindingActionType = ("refactor-function" | "add-tests" | "increase-coverage" | "suppress-file" | "suppress-line" | "split-file")
 /**
  * Audit-mode class of a complexity finding against the base snapshot.
  */
@@ -1254,6 +1254,14 @@ export type InspectSectionStatus = ("ok" | "partial" | "unavailable" | "error")
  * Granularity an [`InspectEvidenceSection`] payload covers.
  */
 export type InspectEvidenceScope = ("symbol" | "file" | "project_filtered_to_file")
+/**
+ * Status of the [`InspectCloudEvidence`] section.
+ */
+export type InspectCloudStatus = ("ok" | "no_key" | "plan_required" | "unavailable" | "untracked")
+/**
+ * How a local function was paired with a deployed function.
+ */
+export type InspectCloudMatch = ("stable_id" | "name_ordinal")
 /**
  * Whether a whole-word text search for an export name finds a consumer that
  * the module graph resolves. The levels sort from best to worst.
@@ -1368,6 +1376,14 @@ export type CoverageSetupPackageManager = ("npm" | "pnpm" | "yarn" | "bun")
  * Runtime environment coverage capture must instrument.
  */
 export type CoverageSetupRuntimeTarget = ("node" | "browser")
+/**
+ * CI provider of a Fallow Cloud setup plan.
+ */
+export type CoverageSetupCiProvider = "github_actions"
+/**
+ * Outcome of `fallow coverage setup --cloud --wait`.
+ */
+export type CoverageSetupWaitOutcome = ("complete" | "timeout" | "error")
 /**
  * Schema-version discriminator for [`CoverageAnalyzeOutput`].
  */
@@ -1760,11 +1776,15 @@ export type SimilarCodeCacheClearSchemaVersion = "1"
 /**
  * Version singleton for a mutation report.
  */
-export type MutationSchemaVersion = "1"
+export type MutationSchemaVersion = "2"
 /**
  * Why a run is partial.
  */
 export type MutationIncompleteReason = ("runtime-error" | "mutant-limit" | "time-budget" | "skipped-files" | "unloaded-files" | "test-files-not-discovered" | "baseline-failure" | "worktree-changed" | "typecheck-failed" | "worktree-unchecked")
+/**
+ * The quality of observed test-to-mutant evidence.
+ */
+export type MutationKillMatrixStatus = ("complete" | "incomplete" | "unavailable")
 /**
  * Which code a run mutates.
  */
@@ -1792,7 +1812,7 @@ export type MutationPlanDisposition = ("planned" | "pending" | "no_coverage" | "
 /**
  * Version singleton for a mutation inspect packet.
  */
-export type MutationInspectSchemaVersion = "1"
+export type MutationInspectSchemaVersion = "2"
 /**
  * Whether the saved report still describes the current file.
  */
@@ -8027,11 +8047,12 @@ export interface HealthFinding {
  */
 path: string
 /**
- * Function name, or a synthesized name for anonymous functions.
+ * Function name, or a synthesized name for anonymous functions. A
+ * file-length finding has the name `<file>`.
  */
 name: string
 /**
- * 1-based line the function starts on.
+ * 1-based line the function starts on. A file-length finding has `1`.
  */
 line: number
 /**
@@ -8055,7 +8076,8 @@ standard_cyclomatic?: (number | null)
  */
 cognitive: number
 /**
- * Lines of code in the function body.
+ * Lines of code in the function body. On a file-length finding, the
+ * physical line count of the file.
  */
 line_count: number
 /**
@@ -8151,6 +8173,12 @@ effective_thresholds?: (HealthEffectiveThresholds | null)
  * Source of the effective thresholds. Omitted when thresholds are global.
  */
 threshold_source?: (ThresholdSource | null)
+/**
+ * File-length ceiling in physical lines that the file exceeded. Present
+ * only on a file-level finding (`exceeded: "file_lines"`), where
+ * `line_count` holds the physical line count of the file.
+ */
+max_file_lines?: (number | null)
 /**
  * Machine-actionable fix and suppress hints.
  */
@@ -8497,7 +8525,9 @@ files_analyzed: number
  */
 functions_analyzed: number
 /**
- * Functions exceeding at least one complexity or CRAP threshold.
+ * Complexity findings before `--top`: functions exceeding at least one
+ * complexity or CRAP threshold, plus file-length findings
+ * (`exceeded: "file_lines"`).
  */
 functions_above_threshold: number
 /**
@@ -8525,6 +8555,12 @@ max_crap_threshold: number
  * here; this is the global default.
  */
 max_unit_size_threshold: number
+/**
+ * Global file-length ceiling (`health.maxFileLines` or
+ * `--max-file-lines`) in physical lines. Absent when the file-length
+ * check is off.
+ */
+max_file_lines_threshold?: (number | null)
 /**
  * Files with a computed maintainability score; absent when file scoring
  * did not run.
@@ -8654,6 +8690,10 @@ max_crap?: (number | null)
  * Unit-size ceiling set by the override, when it sets one.
  */
 max_unit_size?: (number | null)
+/**
+ * File-length ceiling set by the override, when it sets one.
+ */
+max_file_lines?: (number | null)
 }
 /**
  * Current complexity metrics for a matched threshold override entry.
@@ -11085,13 +11125,10 @@ defined_font_faces: string[]
 referenced_font_families: string[]
 }
 /**
- * Structural CSS metrics for a single style rule, computed from the parsed CSS
- * syntax tree. A rule is recorded only when it crosses a structural floor (an
- * id selector, a complex selector, a `!important` declaration, or deep
- * nesting), so the vector stays bounded on normal stylesheets.
- *
- * Not persisted in the extraction cache: `fallow health` computes these
- * on demand from the CSS source, so there is no `bitcode` derive.
+ * Structural CSS metrics for one style rule of the parsed CSS. Only a rule
+ * over a structural floor (an id selector, a complex selector, `!important`,
+ * or deep nesting) is recorded, so the vector stays bounded. Not cached:
+ * `fallow health` computes these from the CSS source (no `bitcode` derive).
  */
 export interface CssRuleMetric {
 /**
@@ -12276,6 +12313,12 @@ symbol_impact?: (InspectEvidenceSection | null)
  * Present only for a symbol target in type-aware mode.
  */
 targeted_tests?: (InspectEvidenceSection | null)
+/**
+ * OPT-IN Fallow Cloud production evidence for a file target. Present
+ * only when `--cloud` was requested. A missing key, a plan gate or an
+ * unreachable cloud is a section status, never a failed run.
+ */
+cloud?: (InspectCloudEvidence | null)
 }
 /**
  * One evidence section: status, the scope the evidence covers, and either a
@@ -12295,6 +12338,161 @@ data?: {
 [k: string]: unknown
 }
 }
+/**
+ * `evidence.cloud` block: production data of the target file from Fallow
+ * Cloud, paired with the functions of the local file.
+ *
+ * `null` in a count means "not measured", never zero.
+ */
+export interface InspectCloudEvidence {
+status: InspectCloudStatus
+/**
+ * Explanation for a status other than `ok`, or a note on an `ok`
+ * section (for example that the cloud left out functions).
+ */
+message?: (string | null)
+/**
+ * Fallow Cloud repository that was read, when it was resolved.
+ */
+repo?: (string | null)
+/**
+ * Newest deployment commit with data for the file.
+ */
+latest_sha?: (string | null)
+/**
+ * Days of production data the cloud read covers.
+ */
+period_days?: (number | null)
+/**
+ * File summary from the cloud. `None` when the cloud was not read.
+ */
+summary?: (InspectCloudSummary | null)
+/**
+ * Local functions paired with a deployed function.
+ */
+functions: InspectCloudFunction[]
+/**
+ * Local functions without a deployed function.
+ */
+unpaired_local: InspectCloudUnpairedFunction[]
+}
+/**
+ * File summary of the [`InspectCloudEvidence`] section.
+ */
+export interface InspectCloudSummary {
+/**
+ * Deployed functions of the file.
+ */
+functions: number
+/**
+ * Functions that ran in the period.
+ */
+called: number
+/**
+ * Functions that were tracked and did not run.
+ */
+never_called: number
+/**
+ * Functions without production data.
+ */
+untracked: number
+/**
+ * Calls of all functions of the file. `None` when not measured.
+ */
+calls?: (number | null)
+/**
+ * Error groups of the file. `None` when not measured.
+ */
+error_groups?: (number | null)
+/**
+ * Error events of the file. `None` when not measured.
+ */
+error_events?: (number | null)
+/**
+ * One-line summary from the cloud.
+ */
+text: string
+}
+/**
+ * One local function with its production data.
+ */
+export interface InspectCloudFunction {
+/**
+ * Function name in the local file.
+ */
+name: string
+/**
+ * 1-based start line in the local file.
+ */
+line: number
+/**
+ * Stable id of the deployed function.
+ */
+stable_id?: (string | null)
+match: InspectCloudMatch
+/**
+ * Tracking state in the current deployment: `called`, `never_called` or
+ * `untracked`.
+ */
+state: string
+/**
+ * Tracking state over the whole period, earlier deployments included.
+ * `called` with `state` `never_called` means that the function did not
+ * run in this deployment, but ran in an earlier one. `None` when the
+ * cloud does not say.
+ */
+period_state?: (string | null)
+/**
+ * Calls in the period. `None` when not measured.
+ */
+calls?: (number | null)
+/**
+ * Error counts. `None` when error capture did not cover the function.
+ */
+errors?: (InspectCloudErrors | null)
+/**
+ * Self CPU milliseconds per profiled hour. `None` when not measured.
+ */
+cpu_ms_per_hour?: (number | null)
+/**
+ * Branch ranges that never ran. `None` when not measured.
+ */
+never_run_ranges?: (number | null)
+/**
+ * One-line summary from the cloud.
+ */
+summary: string
+}
+/**
+ * Error counts of one function.
+ */
+export interface InspectCloudErrors {
+/**
+ * Error groups attributed to the function.
+ */
+groups: number
+/**
+ * Error events attributed to the function.
+ */
+events: number
+}
+/**
+ * One local function without a deployed function.
+ */
+export interface InspectCloudUnpairedFunction {
+/**
+ * Function name in the local file.
+ */
+name: string
+/**
+ * 1-based start line in the local file.
+ */
+line: number
+/**
+ * Why the function has no production data.
+ */
+note: string
+}
 /**
  * Result of tracing an export: why it is considered used or unused.
  */
@@ -13693,6 +13891,10 @@ next_steps: string[]
  * Non-fatal problems encountered during detection.
  */
 warnings: string[]
+/**
+ * Fallow Cloud plan, present only for `fallow coverage setup --cloud`.
+ */
+cloud?: (CoverageSetupCloud | null)
 /**
  * `_meta` block with docs and field definitions, when requested.
  */
@@ -13768,6 +13970,112 @@ path: string
  */
 content: string
 }
+/**
+ * Fallow Cloud plan of `fallow coverage setup --cloud`.
+ *
+ * The beacon, the inventory, the source maps and the deployment registration
+ * must all carry the same commit SHA. The plan names only the environment
+ * variable names of keys, never a key value.
+ */
+export interface CoverageSetupCloud {
+/**
+ * Fallow Cloud project id (`owner/repo`), or null when it was not detected.
+ */
+project_id?: (string | null)
+/**
+ * Commit SHA that `--wait` checks: `--git-sha`, else `HEAD` of the
+ * working tree, or null outside a git repository.
+ */
+git_sha?: (string | null)
+/**
+ * Fallow Cloud API base URL.
+ */
+endpoint: string
+/**
+ * Environment variable that holds the full API key in CI and on the server.
+ */
+api_key_env: string
+/**
+ * Environment variable that holds the ingest-only browser key, when a
+ * member runs in the browser.
+ */
+browser_key_env?: (string | null)
+/**
+ * Environment variables the server snippets read the deployed commit SHA
+ * from, in order.
+ */
+commit_sha_env: string[]
+ci: CoverageSetupCi
+source_maps: CoverageSetupSourceMaps
+/**
+ * Activation endpoint that reports each setup step, or null without a
+ * project id.
+ */
+activation_url?: (string | null)
+/**
+ * Command that waits until the cloud reports every step as done.
+ */
+wait_command: string
+/**
+ * Result of `--wait`, present only when the command waited.
+ */
+wait?: (CoverageSetupWait | null)
+}
+/**
+ * CI steps of a Fallow Cloud setup plan.
+ */
+export interface CoverageSetupCi {
+provider: CoverageSetupCiProvider
+/**
+ * Existing workflow files that look like a deploy workflow, relative to
+ * the project root.
+ */
+workflows_detected: string[]
+/**
+ * Workflow steps to add to the job that builds and deploys.
+ */
+steps: string
+/**
+ * Where the steps go and what they need.
+ */
+instructions: string
+}
+/**
+ * Source map guidance of a Fallow Cloud setup plan.
+ */
+export interface CoverageSetupSourceMaps {
+/**
+ * Whether the CI steps upload source maps.
+ */
+needed: boolean
+/**
+ * Build output directories the maps are uploaded from, one per bundled
+ * workspace member, relative to the project root. Empty when no upload
+ * is needed.
+ */
+dirs: string[]
+/**
+ * Why the upload is or is not needed.
+ */
+reason: string
+}
+/**
+ * Result of `fallow coverage setup --cloud --wait`.
+ */
+export interface CoverageSetupWait {
+outcome: CoverageSetupWaitOutcome
+/**
+ * The last activation response body (`data`) from the cloud, unchanged,
+ * or null when no read succeeded. New step ids and states can appear.
+ */
+activation?: {
+[k: string]: unknown
+}
+/**
+ * Error text when the outcome is `error`.
+ */
+message?: (string | null)
+}
 /**
  * Envelope emitted by `fallow coverage analyze --format json`.
  */
@@ -17870,7 +18178,7 @@ affected_count: number
  * representative files, NEVER to enumerate the blast radius or to infer its
  * shape. Because it is a prefix of the sorted set, it clusters in whichever
  * directory sorts first. To reconstruct the full set, run
- * `fallow check --impact-closure <path>` once per changed file and union the
+ * `fallow dead-code --impact-closure <path>` once per changed file and union the
  * results: that flag seeds from a single file, so no single command
  * reproduces this changeset-wide union.
  */
@@ -19911,6 +20219,7 @@ schema_version: MutationSchemaVersion
 version: ToolVersion
 elapsed_ms: ElapsedMs
 completion: MutationCompletion
+kill_matrix: MutationKillMatrix
 scope: MutationScopeOutput
 /**
  * The runner. Absent when no companion started, for example when no
@@ -19988,6 +20297,58 @@ status: MutationCompletionStatus
  */
 reasons: MutationIncompleteReason[]
 }
+/**
+ * Redundancy signals over the observed mutants. Candidates need review.
+ * Removing candidates together can remove all tests for a mutant.
+ */
+export interface MutationKillMatrix {
+status: MutationKillMatrixStatus
+/**
+ * Why evidence is unavailable or incomplete, sorted.
+ */
+reasons: string[]
+/**
+ * Each eligible test with observed coverage, sorted by test id.
+ */
+tests: MutationTestKillRow[]
+/**
+ * Tests with nonempty kills and no unique kills, sorted by test id.
+ */
+candidates: string[]
+/**
+ * Tests with coverage and no observed kills, sorted by test id.
+ */
+coverage_without_kills: string[]
+}
+/**
+ * The observed mutant kills of one eligible test.
+ */
+export interface MutationTestKillRow {
+/**
+ * The runner test id.
+ */
+test_id: string
+/**
+ * The root-relative test file.
+ */
+file: string
+/**
+ * The observed killed mutant ids, sorted.
+ */
+kills: string[]
+/**
+ * The mutant ids that no other eligible test kills, sorted.
+ */
+unique_kills: string[]
+/**
+ * The tests whose kill sets contain this full kill set, sorted.
+ */
+subsuming_tests: string[]
+/**
+ * Conservative evidence notes, sorted.
+ */
+notes: string[]
+}
 /**
  * The scope of a plan or a run.
  */
@@ -20170,15 +20531,25 @@ prune_reason?: (string | null)
  * The test that killed the mutant in this run. Absent for a kill by an
  * error outside a test.
  *
- * This is evidence of one run, not a stable fact. A run stops at the
- * first failing test, and it runs the fastest covering test first, so a
- * second run on the same code can name another covering test. No
+ * This is evidence of one run, not a stable fact. A normal run stops at
+ * the first failing test. A kill matrix run retains each failing test
+ * in `killing_tests`. Tests run in measured fastest-first order, so a
+ * second run on the same code can name another first killer. No
  * fingerprint or baseline comparison uses this field.
  *
  * The retry of a survivor also runs the other tests of its test files,
  * so this test can be absent from `covering_tests`.
  */
 killed_by?: (string | null)
+/**
+ * All observed failing tests, sorted. Timeouts do not count. Empty
+ * outside `--kill-matrix`; `killed_by` keeps the first killer.
+ */
+killing_tests: string[]
+/**
+ * True only for exact requested membership with terminal pass or fail results.
+ */
+kill_matrix_complete: boolean
 /**
  * The tests that reached the mutant in the dry run, sorted by test id.
  */
@@ -20287,6 +20658,15 @@ duration_ms?: (number | null)
  * The test that killed the mutant in this run.
  */
 killed_by?: (string | null)
+/**
+ * All observed failing tests, sorted. Timeouts do not count. Empty
+ * outside `--kill-matrix`; `killed_by` keeps the first killer.
+ */
+killing_tests: string[]
+/**
+ * True only for exact requested membership with terminal pass or fail results.
+ */
+kill_matrix_complete: boolean
 /**
  * How the run detected the mutant. Absent for a run that did not detect
  * it, and absent when the runner did not state the kind.
@@ -20753,6 +21133,15 @@ static_test_files: string[]
  * The test that killed the mutant in the run of the report.
  */
 killed_by?: (string | null)
+/**
+ * All observed failing tests, sorted. Timeouts do not count. Empty
+ * outside `--kill-matrix`; `killed_by` keeps the first killer.
+ */
+killing_tests: string[]
+/**
+ * True only for exact requested membership with terminal pass or fail results.
+ */
+kill_matrix_complete: boolean
 }
 /**
  * The code of one mutant, from the current file.