fallow 2.89.0 → 2.91.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "2.89.0",
+  "version": "2.91.0",
   "description": "Deterministic codebase intelligence for TypeScript and JavaScript. Quality, risk, architecture, dependencies, duplication, and safe cleanup evidence for humans, CI, and agents. Optional runtime intelligence layer (Fallow Runtime) adds production execution evidence. Rust-native, sub-second, 96 framework plugins.",
   "license": "MIT",
   "repository": {
@@ -83,13 +83,13 @@
     "@tanstack/intent": "0.0.41"
   },
   "optionalDependencies": {
-    "@fallow-cli/darwin-arm64": "2.89.0",
-    "@fallow-cli/darwin-x64": "2.89.0",
-    "@fallow-cli/linux-x64-gnu": "2.89.0",
-    "@fallow-cli/linux-arm64-gnu": "2.89.0",
-    "@fallow-cli/linux-x64-musl": "2.89.0",
-    "@fallow-cli/linux-arm64-musl": "2.89.0",
-    "@fallow-cli/win32-arm64-msvc": "2.89.0",
-    "@fallow-cli/win32-x64-msvc": "2.89.0"
+    "@fallow-cli/darwin-arm64": "2.91.0",
+    "@fallow-cli/darwin-x64": "2.91.0",
+    "@fallow-cli/linux-x64-gnu": "2.91.0",
+    "@fallow-cli/linux-arm64-gnu": "2.91.0",
+    "@fallow-cli/linux-x64-musl": "2.91.0",
+    "@fallow-cli/linux-arm64-musl": "2.91.0",
+    "@fallow-cli/win32-arm64-msvc": "2.91.0",
+    "@fallow-cli/win32-x64-msvc": "2.91.0"
   }
 }

package/schema.json

@@ -1188,11 +1188,11 @@
       ]
     },
     "SecurityConfig": {
-      "description": "Scopes the data-driven security matcher catalogue used by `fallow security`.\nAn absent block (or both `include`/`exclude` unset) admits every category.",
+      "description": "Scopes the security categories used by `fallow security`. An absent block\nadmits every catalogue category. `hardcoded-secret` is include-required and\nonly runs when explicitly listed in `security.categories.include`.",
       "type": "object",
       "properties": {
         "categories": {
-          "description": "Include/exclude filter over catalogue category ids (e.g. `dangerous-html`).",
+          "description": "Include/exclude filter over category ids (e.g. `dangerous-html`).",
           "anyOf": [
             {
               "$ref": "#/$defs/SecurityCategories"
@@ -1206,7 +1206,7 @@
       "additionalProperties": false
     },
     "SecurityCategories": {
-      "description": "Include/exclude lists scoping the active security matcher categories. When\n`include` is set, only those categories are active; `exclude` removes\ncategories from the admitted set. Both unset admits every category.",
+      "description": "Include/exclude lists scoping the active security categories. When `include`\nis set, only those categories are active; `exclude` removes categories from\nthe admitted set. Both unset admits catalogue categories. `hardcoded-secret`\nstill requires explicit inclusion.",
       "type": "object",
       "properties": {
         "include": {
@@ -1762,7 +1762,15 @@
     "CacheConfig": {
       "type": "object",
       "properties": {
+        "dir": {
+          "description": "Directory for fallow's persistent analysis cache. Relative paths resolve\nfrom the project root.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
         "maxSizeMb": {
+          "description": "Maximum size of the persistent extraction cache, in megabytes.",
           "type": [
             "integer",
             "null"

package/skills/fallow/SKILL.md

@@ -75,7 +75,7 @@ cargo install fallow-cli        # build from source
 | `health` | Function complexity analysis (also covers Angular templates as synthetic `<template>` findings: external `.html` files via `templateUrl` AND inline `@Component({ template: \`...\` })` literals; suppress external with `<!-- fallow-ignore-file complexity -->` at the top of the `.html` file, suppress inline with `// fallow-ignore-next-line complexity` directly above the `@Component` decorator) | `--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`, `--workspace`, `--changed-workspaces`, `--baseline`, `--save-baseline` |
 | `audit` | Combined dead-code + complexity + duplication for changed files | `--base`, `--gate`, `--production`, `--production-dead-code`, `--production-health`, `--production-dupes`, `--workspace`, `--changed-workspaces`, `--ci`, `--fail-on-issues`, `--explain`, `--explain-skipped`, `--dead-code-baseline`, `--health-baseline`, `--dupes-baseline`, `--max-crap`, `--coverage`, `--coverage-root`, `--include-entry-exports` |
 | `flags` | Detect feature flag patterns (env vars, SDK calls, config objects) | `--top` |
-| `security` | Surface opt-in local security candidates for agent verification (not confirmed vulnerabilities). Two rule families: the graph rule `client-server-leak` (a `"use client"` file reaching a non-public `process.env` secret) and a data-driven `tainted-sink` catalogue across 9 CWE categories (dangerous-html, command-injection, code-injection, sql-injection, ssrf, path-traversal, open-redirect, weak-crypto, unsafe-deserialization). Conservative non-literal trigger; parameterized SQL not flagged. Rules default off; suppress a file with `// fallow-ignore-file security-sink`; scope categories with `security.categories`. | `--format human|json|sarif`, `--changed-since`, `--diff-file`, `--workspace`, `--changed-workspaces`, `--ci`, `--fail-on-issues`, `--sarif-file`, `--summary` |
+| `security` | Surface opt-in local security candidates for agent verification (not confirmed vulnerabilities). Rule families include the graph rule `client-server-leak`, a data-driven `tainted-sink` catalogue, and the include-required `hardcoded-secret` category for provider-prefix credentials and high-entropy literals assigned to secret-shaped identifiers. Most catalogue rows require non-literal input; narrowly literal-aware rows flag deterministic unsafe literals. Rules default off; suppress a file with `// fallow-ignore-file security-sink`; scope categories with `security.categories`. `hardcoded-secret` runs only when listed in `security.categories.include`. | `--format human|json|sarif`, `--changed-since`, `--file`, `--diff-file`, `--workspace`, `--changed-workspaces`, `--surface`, `--ci`, `--fail-on-issues`, `--sarif-file`, `--summary` |
 | `explain` | Explain one issue type without running analysis | `<issue-type>`, `--format json` |
 | `license` | Manage the local license JWT for continuous/cloud runtime monitoring (activate, status, refresh, deactivate) | `activate --trial --email <addr>`, `activate --from-file`, `activate --stdin`, `status`, `refresh`, `deactivate` |
 | `telemetry` | Manage opt-in, off-by-default product telemetry (never collects code, paths, or names). Agents must not enable it; only the user may | `status`, `enable`, `disable`, `inspect --example` |
@@ -118,7 +118,7 @@ When using fallow via MCP (`fallow-mcp`), the following tools are available:
 |------|-------------|
 | `analyze` | Full dead code analysis (unused files/exports/types/dependencies/members + circular dependencies + re-export cycles (barrel files that form a structural loop, silently breaking re-exports) + boundary violations + stale suppressions). Private type leaks are an opt-in API hygiene check via `issue_types: ["private-type-leaks"]`. Set `boundary_violations: true` as a convenience alias for `issue_types: ["boundary-violations"]`. Set `group_by` to `"owner"`, `"directory"`, `"package"`, or `"section"` to partition results. The `section` mode reads GitLab CODEOWNERS `[Section]` headers and emits `owners` metadata per group |
 | `check_changed` | Incremental analysis of files changed since a git ref |
-| `security_candidates` | Unverified local security candidates, not confirmed vulnerabilities (`fallow security --format json`). Read `security_findings[]` for category, CWE, evidence, and trace; verify trace and evidence before editing code. Supports `root`, `config`, `workspace`, `changed_since`, `changed_workspaces`, `no_cache`, and `threads`; inherits `FALLOW_DIFF_FILE` from the server environment for line-level diff scoping; raise `FALLOW_TIMEOUT_SECS` for large repos. |
+| `security_candidates` | Unverified local security candidates, not confirmed vulnerabilities (`fallow security --format json`). Read `security_findings[]` for category, CWE, severity, evidence, trace, optional `reachability`, and blind-spot counters. `severity` is a review-priority tier, not a verified vulnerability verdict. Each finding also carries an agent-actionable `candidate` (`source_kind`/`sink`/`boundary`), an optional `taint_flow` source-to-sink triple, and a stable `finding_id` (equal to the SARIF fingerprint) for cross-run correlation; there is no `impact` field (deciding exploitability is the agent's job). Set `surface: true` to include top-level `attack_surface[]` entries with defensive-boundary prompts for a verifier. `reachability.untrusted_source_trace` is module-level import context only and does not prove value flow; `reachability.taint_confidence` tiers each reachable candidate as `arg-level` (sink argument traces to a same-module source read, strong) or `module-level` (only the module is import-reachable from a source, weak), so tier from this field instead of the evidence text. Verify trace, reachability context, severity, and evidence before editing code. Supports `root`, `config`, `workspace`, `paths`, `changed_since`, `changed_workspaces`, `surface`, `no_cache`, and `threads`; `paths` forwards repeated `fallow security --file` filters for finding anchors, trace hops, or untrusted-source reachability trace hops. See <https://docs.fallow.tools/cli/security-agent-verification> for the verifier packet and verdict recipe. Inherits `FALLOW_DIFF_FILE` from the server environment for line-level diff scoping; raise `FALLOW_TIMEOUT_SECS` for large repos. |
 | `find_dupes` | Code duplication detection. Set `changed_since` to scope to changed files since a git ref. Set `min_occurrences` (≥ 2, default 2) to hide pair-only clones and focus on widespread copy-paste; JSON gains `stats.clone_groups_below_min_occurrences` when the filter hides anything. Each `clone_groups[]` entry carries a stable `fingerprint`, usually `dup:<8hex>` and widened only on rare report collisions; pass it to `trace_clone` to deep-dive that group |
 | `fix_preview` | Dry-run auto-fix preview |
 | `fix_apply` | Apply auto-fixes (destructive) |
@@ -366,6 +366,8 @@ Config fields:
 - `ignoreExportsUsedInFile`: knip-compatible; suppress unused-export findings when the exported symbol is referenced inside the file that declares it. Boolean (`true` covers all kinds) or `{ "type": true, "interface": true }` object form for knip parity. Fallow groups type aliases and interfaces under the same `unused-types` issue, so both type-kind fields behave identically. References inside the export specifier itself (`export { foo }`, `export default foo`) do not count as same-file uses; those exports are still reported when no other in-file expression references the binding
 - `publicPackages`: workspace packages that are public libraries; exported API surface from these packages is not flagged as unused
 - `dynamicallyLoaded`: glob patterns for files loaded at runtime (plugin dirs, locale files); treated as always-used
+- `cache.dir`: override the persistent extraction cache directory. `FALLOW_CACHE_DIR` wins over this config field, and `--no-cache` disables caching entirely
+- `cache.maxSizeMb`: cap the serialized extraction cache size in megabytes. `FALLOW_CACHE_MAX_SIZE` wins over this config field
 - `usedClassMembers`: class method/property names that extend the built-in Angular/React lifecycle allowlist with framework-invoked names. Each entry is a plain string (global suppression) or a scoped object `{ extends?, implements?, members }` matching only classes with the given heritage. Strings can be exact names (`"agInit"`) or glob patterns (`"*"` matches every member, `"enter*"` prefix, `"*Handler"` suffix, `"on*Event"` combined). Use scoped rules for common names like `refresh` or `execute` to avoid false negatives on unrelated classes; global strings for unique names like `agInit`. Example: `["agInit", { "implements": "ICellRendererAngularComp", "members": ["refresh"] }, { "extends": "BaseCommand", "members": ["execute"] }, { "extends": "GrammarBaseListener", "members": ["enter*", "exit*"] }]`. Glob patterns that match zero members emit a `WARN` so dead allowlist entries surface. An unconstrained scoped rule (no `extends` or `implements`) is rejected at load time. Use plugin-level `usedClassMembers` in a `.fallow/plugins/*.jsonc` file for library-specific allowlists
 - `resolve.conditions`: additional package.json `exports` / `imports` condition names to honor during module resolution. Baseline conditions (`development`, `import`, `require`, `default`, `types`, `node`, plus `react-native` / `browser` under RN/Expo) are always included; user entries prepend ahead of them. Use for community conditions like `worker`, `edge-light`, `deno`, or custom bundler conditions. Example: `{ "resolve": { "conditions": ["worker", "edge-light"] } }`
 

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

@@ -40,9 +40,12 @@ Analyzes the project for unused files, exports, dependencies, types, members, an
 |------|------|---------|-------------|
 | `--format` | `human\|json\|sarif\|compact\|markdown\|codeclimate\|gitlab-codequality\|pr-comment-github\|pr-comment-gitlab\|review-github\|review-gitlab` | `human` | Output format |
 | `--quiet` | bool | `false` | Suppress progress bars and timing on stderr |
+| `-o, --output-file` | path | (none) | Write the report to a file instead of stdout, for any `--format` (no ANSI codes). Progress and a confirmation stay on stderr (suppressed by `--quiet`). Valid with dead-code/dupes/health/security/bare; composes with `--sarif-file`. |
 | `--legacy-envelope` | bool | `false` | Remove the top-level `kind` field from typed JSON roots for one migration cycle |
 | `--changed-since` | string | — | Only analyze files changed since a git ref (e.g., `main`, `HEAD~3`) |
+| `--max-file-size` | int (MB) | `5` | Skip source files larger than N megabytes at discovery instead of parsing them (`0` disables). Guards against the OOM a single multi-MB generated/vendored/bundled file causes on large repos. `.d.ts` files are always analyzed. Skipped files appear on stderr and in `--format json` under `workspace_diagnostics` (`kind: "skipped-large-file"`). Also settable via `FALLOW_MAX_FILE_SIZE`. Global flag. |
 | `--production` | bool | `false` | Exclude test/dev files, only start/build scripts (applies to every analysis) |
+| `--no-production` | bool | `false` | Force production mode off, overriding a project config's `production: true` (applies to every analysis; conflicts with `--production`) |
 | `--production-dead-code` | bool | `false` | Per-analysis production mode for dead-code. Bare combined runs and `fallow audit` only. |
 | `--production-health` | bool | `false` | Per-analysis production mode for health. Bare combined runs and `fallow audit` only. |
 | `--production-dupes` | bool | `false` | Per-analysis production mode for duplication. Bare combined runs and `fallow audit` only. |
@@ -234,7 +237,7 @@ Auto-removes unused exports, dependencies, enum members, and pnpm catalog entrie
 
 ### On-disk drift protection
 
-`fallow fix` captures every parsed source file's xxh3 content hash during the in-process analysis and recomputes it at fix time. Files whose hash drifted between analysis and write (parallel editor save, CI rebase, concurrent tool) are skipped with `{"type": "skipped", "path": "...", "skipped": true, "skip_reason": "content_changed"}` in the JSON output and `Skipping <path>: file content changed since fallow check ran. Re-run fallow fix to refresh the analysis first.` on stderr (gated on non-quiet). A run with any content-changed skip exits with code 2 so CI does not treat the partial run as a clean no-op. The JSON envelope's top-level `skipped_content_changed: number` is always present and disjoint from `skipped` (which still tallies catalog / YAML guard skips only). Per-file writes are batched: each rewrite is staged to a sibling temp file, and the orchestrator promotes the batch only after every stage succeeds. A stage failure leaves every target file at its original content. Hash precondition covers source files (TS, JS, Vue, Svelte, Astro, MDX); `package.json` and `pnpm-workspace.yaml` are not in the captured hash map because the extract layer does not parse them, but the dep and catalog fixers re-parse those files at fix time as the natural safety net.
+`fallow fix` captures every parsed source file's xxh3 content hash during the in-process analysis and recomputes it at fix time. Files whose hash drifted between analysis and write (parallel editor save, CI rebase, concurrent tool) are skipped with `{"type": "skipped", "path": "...", "skipped": true, "skip_reason": "content_changed"}` in the JSON output and `Skipping <path>: file content changed since fallow dead-code ran. Re-run fallow fix to refresh the analysis first.` on stderr (gated on non-quiet). A run with any content-changed skip exits with code 2 so CI does not treat the partial run as a clean no-op. The JSON envelope's top-level `skipped_content_changed: number` is always present and disjoint from `skipped` (which still tallies catalog / YAML guard skips only). Per-file writes are batched: each rewrite is staged to a sibling temp file, and the orchestrator promotes the batch only after every stage succeeds. A stage failure leaves every target file at its original content. Hash precondition covers source files (TS, JS, Vue, Svelte, Astro, MDX); `package.json` and `pnpm-workspace.yaml` are not in the captured hash map because the extract layer does not parse them, but the dep and catalog fixers re-parse those files at fix time as the natural safety net.
 
 ### Low-confidence export removals
 
@@ -243,7 +246,7 @@ Issue #602: `fallow fix` withholds unused-export removals when the consumer may
 - **Off-graph consumer directories.** The file is under any of `__mocks__`, `__fixtures__`, `fixtures`, `e2e`, `e2e-tests`, `cypress`, `playwright`, `examples`, `evals`, `golden` (matched on any path segment). Catches Vitest mock aliases, off-workspace e2e suites, and fixture / golden harnesses. Plain `test` / `tests` / `__tests__` are deliberately NOT on the list, so genuinely-dead test helpers still auto-remove.
 - **Files with an unresolved import.** The file itself imports something fallow could not resolve, so its local usage graph is incomplete.
 
-JSON output carries `{"type": "skipped", "path": "...", "skipped": true, "skip_reason": "low_confidence_off_graph"}` (or `"low_confidence_unresolved_imports"`) plus a top-level counter `skipped_low_confidence_exports: number` (always present), disjoint from `skipped`. Unlike the drift and encoding skips this is INTENTIONAL and does NOT change the exit code; the export stays reported by `fallow check` for manual review. High-confidence exports in normal source files are removed unchanged. The AI agent should report kept exports to the user and let them decide whether the export is truly unused before removing it by hand.
+JSON output carries `{"type": "skipped", "path": "...", "skipped": true, "skip_reason": "low_confidence_off_graph"}` (or `"low_confidence_unresolved_imports"`) plus a top-level counter `skipped_low_confidence_exports: number` (always present), disjoint from `skipped`. Unlike the drift and encoding skips this is INTENTIONAL and does NOT change the exit code; the export stays reported by `fallow dead-code` for manual review. High-confidence exports in normal source files are removed unchanged. The AI agent should report kept exports to the user and let them decide whether the export is truly unused before removing it by hand.
 
 ### File encoding contract
 
@@ -294,7 +297,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 check --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`) 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 `--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`.
 
@@ -495,7 +498,7 @@ fallow health --format json --quiet --trend
 {
   "kind": "health",
   "schema_version": 7,
-  "version": "2.89.0",
+  "version": "2.91.0",
   "elapsed_ms": 32,
   "summary": {
     "files_analyzed": 482,
@@ -805,6 +808,7 @@ Audits changed files for dead code, complexity, and duplication. Returns a verdi
 | `--base` | string | auto-detect | Git ref to compare against (alias for `--changed-since`) |
 | `--gate` | `new-only\|all` | `new-only` | Which findings affect the verdict. `new-only` gates only introduced findings; `all` gates every finding in changed files and skips the extra base-snapshot attribution pass. |
 | `--production` | bool | false | Exclude test/story/dev files (applies to dead-code, health, and dupes) |
+| `--no-production` | bool | false | Force production mode off, overriding a project config's `production: true` (conflicts with `--production`) |
 | `--production-dead-code` | bool | false | Per-analysis production mode for the dead-code sub-analysis only |
 | `--production-health` | bool | false | Per-analysis production mode for the health sub-analysis only |
 | `--production-dupes` | bool | false | Per-analysis production mode for the duplication sub-analysis only |
@@ -885,7 +889,7 @@ fallow audit \
 {
   "kind": "audit",
   "schema_version": 7,
-  "version": "2.89.0",
+  "version": "2.91.0",
   "command": "audit",
   "verdict": "fail",
   "changed_files_count": 12,
@@ -958,7 +962,7 @@ fallow flags --format json --quiet --workspace my-package
 ```json
 {
   "schema_version": 7,
-  "version": "2.89.0",
+  "version": "2.91.0",
   "elapsed_ms": 116,
   "feature_flags": [],
   "total_flags": 0
@@ -973,21 +977,57 @@ Surfaces local security candidates for agent or human verification. The first ru
 
 Findings are not confirmed vulnerabilities. Use the structural trace to verify whether the value can actually reach client-bundled code. Public env conventions (`NODE_ENV`, `NEXT_PUBLIC_*`, `VITE_*`, `NUXT_PUBLIC_*`, `REACT_APP_*`, `PUBLIC_*`, `GATSBY_*`, `EXPO_PUBLIC_*`, `STORYBOOK_*`) are excluded.
 
-The second rule family is a data-driven `tainted-sink` catalogue: syntactic dangerous-sink candidates across 9 CWE categories. A candidate fires only when the relevant argument is non-literal, so a fully-literal value (`el.innerHTML = "<b>x</b>"`, `child_process.exec("ls")`) never fires; fallow prefers false-negatives over false-positives.
+The second rule family is a data-driven `tainted-sink` catalogue: syntactic dangerous-sink candidates across the catalogue categories listed below. Most rows require a non-literal argument; narrowly literal-aware rows flag deterministic unsafe literals such as wildcard `postMessage` origins, weak crypto algorithms, disabled TLS validation, and JWT algorithm issues. Fallow prefers false-negatives over false-positives.
 
 | Category | CWE | Sink |
 |----------|-----|------|
 | `dangerous-html` | 79 | `innerHTML` / `outerHTML` / `insertAdjacentHTML` / `dangerouslySetInnerHTML` |
+| `template-escape-bypass` | 79 | template-engine `SafeString(...)` wrapping a non-literal value |
 | `command-injection` | 78 | `child_process` `exec` / `execSync` / `spawn` / `spawnSync` (provenance-gated to `node:child_process`) |
 | `code-injection` | 94 | `eval` / `vm.runInNewContext` |
+| `dynamic-regex` | 1333 | `RegExp(...)` / `new RegExp(...)` with a non-literal pattern |
+| `redos-regex` | 1333 | vulnerable regex literals tested with source-backed input |
+| `resource-amplification` | 400 | source-backed size into `Array(...)` / `new Array(...)` / `Buffer.alloc*` / `String.prototype.repeat` / `padStart` / `padEnd` (directly `Math.min`-clamped sizes stay quiet) |
+| `dynamic-module-load` | 95 | dynamic `require(...)` |
 | `sql-injection` | 89 | string concat or interpolated template into `.query()` / `.execute()`, and `sql.raw(...)`. Parameterized `` sql`${x}` `` and the object form `.execute({ sql, args })` are NOT flagged |
-| `ssrf` | 918 | `fetch` / `axios` / `http(s).request` |
-| `path-traversal` | 22 | `fs.*` / `path.join` / `path.resolve` |
-| `open-redirect` | 601 | `res.redirect` |
+| `ssrf` | 918 | `fetch` / `got` / `ky` / `needle` / `request` / `axios` / `superagent` / `undici` / `http(s).request` |
+| `path-traversal` | 22 | `path.join` / `path.resolve` / `node:fs` path methods / route `sendFile` |
+| `header-injection` | 113 | response `setHeader` / `writeHead` |
+| `open-redirect` | 601 | `res.redirect` / `location.href` / `location.assign` / `window.open` |
+| `postmessage-wildcard-origin` | 346 | `postMessage(..., "*")` |
+| `tls-validation-disabled` | 295 | HTTPS/TLS options with `rejectUnauthorized: false`, plus `NODE_TLS_REJECT_UNAUTHORIZED = "0"` |
+| `cleartext-transport` | 319 | cleartext `http://` URLs in fetch-like calls and WebSocket constructors |
+| `electron-unsafe-webpreferences` | 1188 | Electron `webPreferences` with unsafe literal options |
+| `world-writable-permission` | 732 | `chmod` / `chmodSync` with world-writable modes |
+| `insecure-temp-file` | 377 | predictable temporary file paths in `fs` writes |
+| `mysql-multiple-statements` | 89 | MySQL connection options with `multipleStatements: true` |
+| `permissive-cors` | 942 | CORS wildcard origin with credentials |
+| `insecure-cookie` | 614 | cookie options missing or disabling `httpOnly` / `secure` |
+| `mass-assignment` | 915 | source-backed `Object.assign(target, source)` |
 | `weak-crypto` | 327 | runtime-selectable hash / cipher algorithm |
+| `deprecated-cipher` | 327 | `crypto.createCipher` / `createDecipher` |
+| `insecure-randomness` | 338 | `crypto.pseudoRandomBytes(...)` and token-like `Math.random()` use |
+| `jwt-alg-none` | 347 | JWT signing with algorithm `none` |
+| `jwt-verify-missing-algorithms` | 347 | `jsonwebtoken` verify calls missing an `algorithms` allowlist |
+| `unsafe-buffer-alloc` | 1188 | `Buffer.allocUnsafe` / `allocUnsafeSlow` |
 | `unsafe-deserialization` | 502 | `js-yaml` `load` / `node-serialize` |
-
-Build-config and test files are excluded from candidate generation. Both rule families default to `off` and are surfaced only by `fallow security`, never under bare `fallow` or the `audit` gate. Scope which catalogue categories run with `security.categories` include / exclude lists in config.
+| `angular-trusted-html` | 79 | Angular `bypassSecurityTrust*` |
+| `nextjs-open-redirect` | 601 | Next.js `redirect` / `permanentRedirect` |
+| `dom-document-write` | 79 | `document.write` / `document.writeln` |
+| `jquery-html` | 79 | jQuery `.html(value)` |
+| `route-send-file` | 22 | Express / Fastify / Hono route `sendFile` |
+| `webview-injection` | 94 | react-native-webview injected JavaScript |
+| `prototype-pollution` | 1321 | `__proto__` writes and recursive merge sources |
+| `zip-slip` | 22 | archive extraction destination paths |
+| `nosql-injection` | 943 | Mongo / Mongoose query object passthrough |
+| `ssti` | 1336 | template engine compile / render calls |
+| `xxe` | 611 | XML parse calls |
+| `secret-pii-log` | 532 | source-backed secrets or request PII reaching logs |
+| `hardcoded-secret` | 798 | provider-prefix credentials and high-entropy literals assigned to secret-shaped identifiers (include-required) |
+| `secret-to-network` | 201 | a non-public `process.env` / `import.meta.env` secret reaching a network call body (`fetch` / `axios` / `got` / ...) via same-identifier flow (include-required) |
+| `xpath-injection` | 643 | `xpath.select` / `select1` with a non-literal expression |
+
+Build-config and test files are excluded from candidate generation. Security rule families default to `off` and are surfaced only by `fallow security`, never under bare `fallow` or the `audit` gate. Scope which catalogue categories run with `security.categories` include / exclude lists in config. `hardcoded-secret` and `secret-to-network` are intentionally include-required and only run when listed in `security.categories.include` (`secret-to-network` is opt-in because legitimate auth is also a secret reaching a network call). Public-by-convention env vars (`NEXT_PUBLIC_`, `VITE_`, ...) are never treated as secrets.
 
 ### Flags
 
@@ -1000,7 +1040,11 @@ Build-config and test files are excluded from candidate generation. Both rule fa
 | `--fail-on-issues` | bool | `false` | Exit 1 when candidates are found |
 | `--sarif-file` | path | none | Write SARIF in addition to the primary output |
 | `--changed-since` | git ref | none | Scope to candidates whose client anchor or trace hops touch changed files |
+| `--file` | path, repeatable | none | Scope output to candidates whose finding anchor or trace hop matches the selected file. The full graph is still analyzed |
 | `--diff-file` | path | none | Scope candidates to added hunks on the client anchor or import trace. Secret-source hops use file-level retention because member-access spans are not yet stored. Use `-` for stdin |
+| `--diff-stdin` | bool | `false` | Read the unified diff from stdin (equivalent to `--diff-file -`) for line-level scoping and the regression gate |
+| `--surface` | bool | `false` | Include the agent-facing `attack_surface[]` inventory in JSON output |
+| `--gate` | `new` | none | Fail (exit code **8**) only when the change introduces a NEW security-sink candidate in the changed lines, not on the whole candidate backlog. Requires a diff source (`--changed-since`, `--diff-file`, or `--diff-stdin`); a diff the gate cannot compute is a loud exit 2, never a green gate. Human output says `REVIEW REQUIRED` (not `FAIL`); SARIF keeps every result at `level: note` with the verdict in `run.properties.fallowGate`; `--format json` carries an additive `gate` block (`mode` / `verdict` / `new_count`) |
 | `--workspace` | string | none | Scope to selected workspace packages |
 | `--changed-workspaces` | git ref | none | Scope to workspaces changed since a git ref |
 
@@ -1010,6 +1054,9 @@ Build-config and test files are excluded from candidate generation. Both rule fa
 fallow security --format json --quiet
 fallow security --ci --sarif-file fallow-security.sarif
 git diff --unified=0 origin/main...HEAD | fallow security --diff-file -
+# Regression gate: fail (exit 8) only on candidates introduced in the changed lines
+fallow security --gate new --changed-since origin/main
+git diff --cached --unified=0 | fallow security --gate new --diff-stdin
 ```
 
 ### JSON Output Structure
@@ -1017,14 +1064,24 @@ git diff --unified=0 origin/main...HEAD | fallow security --diff-file -
 ```json
 {
   "kind": "security",
-  "schema_version": "1",
+  "schema_version": "2",
   "security_findings": [],
   "unresolved_edge_files": 0,
   "unresolved_callee_sites": 0
 }
 ```
 
-Each finding includes `kind`, `path`, `line`, `col`, `evidence`, `trace`, and `actions`. `tainted-sink` findings additionally carry `category` (the catalogue id, e.g. `"dangerous-html"`) and `cwe`; `client-server-leak` findings omit both. `unresolved_edge_files` (client-server-leak) and `unresolved_callee_sites` (tainted-sink) are in-band blind-spot counters: a zero finding count with a non-zero counter is not a clean bill. Suppress a verified false positive with `// fallow-ignore-file security-client-server-leak` (client-server-leak) or `// fallow-ignore-file security-sink` (any tainted-sink category).
+Each finding includes `kind`, `path`, `line`, `col`, `evidence`, `trace`, `actions`, `severity`, and optional `reachability`. `severity` is a review-priority tier (`high`, `medium`, or `low`) derived from reachability, boundary, source-backed, and runtime-hot signals; it is not a verified vulnerability verdict and does not change gate or exit semantics. SARIF maps high and medium candidates to `warning`, and low candidates to `note`. `tainted-sink` findings additionally carry `category` (the catalogue id, e.g. `"dangerous-html"`) and `cwe`; `client-server-leak` findings omit both. `tainted-sink` findings can also include `reachability.untrusted_source_trace` when a module with a known untrusted source imports the sink module; it is ranking and triage context only, not proof that a specific value reaches the sink. When set, `reachability.taint_confidence` tiers the association as `"arg-level"` (the sink argument traces to a same-module source read, strong) or `"module-level"` (only the module is import-reachable from a source, weak); tier from this field rather than the evidence text. For arg-level findings the trace's first hop points at the actual source-read line, and module-level source hops carry the role `"module-source"`. `unresolved_edge_files` (client-server-leak) and `unresolved_callee_sites` (tainted-sink) are in-band blind-spot counters: a zero finding count with a non-zero counter is not a clean bill. Suppress a verified false positive with `// fallow-ignore-file security-client-server-leak` (client-server-leak) or `// fallow-ignore-file security-sink` (any tainted-sink category).
+
+Every finding also carries an agent-actionable `candidate { source_kind, sink, boundary }`, an optional `taint_flow { source, sink, path }`, and a stable `finding_id`:
+
+- `candidate.source_kind`: the untrusted-input kind that reaches the sink, as a stable catalogue id (`"http-request-input"`, `"process-env"`, `"process-argv"`, `"message-event-data"`, `"location-input"`, ...). Absent when no source matched (always absent for `client-server-leak`). Treat an unknown id as an untrusted source of unknown kind; never drop the candidate on that basis.
+- `candidate.sink`: a self-contained sink (`path`, `line`, `col`, `category`, `cwe`, `callee`), actionable without reading the rest of the finding.
+- `candidate.boundary`: `client_server` (a `"use client"` file in the trace), `cross_module` (the source reaches the sink across import hops), and optional `architecture_zone` (`from`/`to`) when the anchor also crosses a declared architecture boundary.
+- `candidate.network`: present only on `secret-to-network` (#890) candidates. `destination` is the network call's URL when it is a static literal (usually intended auth) or absent when the destination is dynamic (the higher-signal exfil case). Use it to triage exfil from intended auth without re-reading source.
+- There is no `impact` field: deciding exploitability is the verifying agent's job; `severity` is only the review-priority tier.
+- `taint_flow`: present only when an untrusted source is import-reachable to the sink. `path` is the compact `{ intra_module, cross_module_hops }` shape; the full ordered hops stay in `reachability.untrusted_source_trace`.
+- `finding_id`: a stable correlation id, identical across runs for the same rule/path/line and identical to the SARIF `partialFingerprints` value, for tracking a candidate across runs and joining JSON with SARIF.
 
 ---
 
@@ -1396,6 +1453,7 @@ Available on all commands:
 | `FALLOW_BIN` | Path to fallow binary (used by the MCP server). |
 | `FALLOW_TIMEOUT_SECS` | MCP server subprocess timeout in seconds (default: `120`). Increase for very large codebases. |
 | `FALLOW_EXTENDS_TIMEOUT_SECS` | Timeout for fetching remote config inheritance in seconds (default: `5`). Do not raise this for untrusted sources. |
+| `FALLOW_CACHE_DIR` | Override the persistent extraction cache directory. Wins over `cache.dir`. Useful for read-only checkouts or CI cache volumes. `--no-cache` disables this knob. |
 | `FALLOW_CACHE_MAX_SIZE` | Maximum on-disk extraction cache (`.fallow/cache.bin`) size in megabytes (default: `256`). Triggers LRU eviction when crossed. Wins over `cache.maxSizeMb` config field. Intended for CI runners with disk quotas. `--no-cache` short-circuits this knob. |
 | `FALLOW_AUDIT_CACHE_MAX_AGE_DAYS` | Max age (in days since last reuse or fresh create) of a persistent reusable `fallow audit` base-snapshot worktree cache. Older entries are reclaimed at the top of the next `fallow audit` invocation (default: `30`). Wins over `audit.cacheMaxAgeDays` config field. `0` disables the GC; invalid values silently fall back to config / default. |
 | `FALLOW_UPDATE_CHECK` | Set to `off`, `0`, `false`, `disabled`, or `no` to disable the human-TTY upgrade nudge and its background latest-version check. `DO_NOT_TRACK`, `FALLOW_TELEMETRY_DISABLED`, and CI also suppress it. |
@@ -1498,7 +1556,7 @@ The HTTP layer mirrors the bash `gh_api_retry` / `curl_retry` helpers: `FALLOW_A
 {
   "kind": "dead-code",
   "schema_version": 7,
-  "version": "2.89.0",
+  "version": "2.91.0",
   "elapsed_ms": 45,
   "total_issues": 12,
   "entry_points": {
@@ -1658,7 +1716,7 @@ When `--baseline` is used in combined output, the JSON includes a `baseline_delt
 {
   "kind": "dupes",
   "schema_version": 7,
-  "version": "2.89.0",
+  "version": "2.91.0",
   "elapsed_ms": 82,
   "total_clones": 15,
   "total_lines_duplicated": 230,
@@ -1702,11 +1760,11 @@ When running `fallow` with no subcommand (all analyses), the JSON output combine
 {
   "kind": "combined",
   "schema_version": 7,
-  "version": "2.89.0",
+  "version": "2.91.0",
   "elapsed_ms": 159,
   "check": {
     "schema_version": 7,
-    "version": "2.89.0",
+    "version": "2.91.0",
     "elapsed_ms": 45,
     "total_issues": 12,
     "unused_files": [],
@@ -1814,6 +1872,12 @@ Config files are searched in priority order: `.fallowrc.json` > `.fallowrc.jsonc
     "ignorePatterns": ["**/*.generated.ts"]
   },
 
+  // Extraction cache settings. FALLOW_CACHE_DIR overrides cache.dir.
+  "cache": {
+    "dir": "/tmp/fallow-cache",
+    "maxSizeMb": 256
+  },
+
   // Architecture boundaries (preset, custom zones/rules, or auto-discovered feature zones)
   // Presets: "layered", "hexagonal", "feature-sliced", "bulletproof"
   // Rules accept an optional `allowTypeOnly: [zones]` list that admits type-only imports

package/types/output-contract.d.ts

@@ -61,6 +61,8 @@ kind: "coverage-setup"
 kind: "coverage-analyze"
 }) | (ListBoundariesOutput & {
 kind: "list-boundaries"
+}) | (WorkspacesOutput & {
+kind: "list-workspaces"
 }) | (HealthOutput & {
 kind: "health"
 }) | (DupesOutput & {
@@ -320,6 +322,12 @@ error: string
 kind: "malformed-tsconfig"
 } | {
 kind: "tsconfig-reference-dir-missing"
+} | {
+/**
+ * On-disk size of the skipped file in bytes.
+ */
+size_bytes: number
+kind: "skipped-large-file"
 })
 /**
  * Discriminant for [`CloneGroupAction::kind`]. Mirrors the action types
@@ -598,16 +606,54 @@ export type ImpactTrendDirection = ("improving" | "declining" | "stable")
  * The `fallow security --format json` schema version. Independently versioned
  * from the main contract, mirroring `ImpactReportSchemaVersion`.
  */
-export type SecuritySchemaVersion = "1"
+export type SecuritySchemaVersion = ("1" | "2")
+/**
+ * Gate mode for `fallow security --gate <mode>` (issue #886). Tier 2 reserves
+ * the value `newly-reachable`.
+ */
+export type SecurityGateMode = "new"
+/**
+ * Gate verdict on the wire. `fail` is the CI-state token; human output renders
+ * it as "REVIEW REQUIRED" because these stay unverified candidates, never
+ * confirmed vulnerabilities.
+ */
+export type SecurityGateVerdict = ("pass" | "fail")
 /**
  * The kind of security candidate. Findings are CANDIDATES for downstream agent
  * verification, NOT verified vulnerabilities.
  */
 export type SecurityFindingKind = ("client-server-leak" | "tainted-sink")
+/**
+ * Verification-priority tier for a security candidate. This is ranking, not an
+ * exploitability verdict.
+ */
+export type SecuritySeverity = ("high" | "medium" | "low")
 /**
  * The role a hop plays in a security finding's structural import trace.
  */
-export type TraceHopRole = ("client-boundary" | "intermediate" | "secret-source" | "sink")
+export type TraceHopRole = ("client-boundary" | "untrusted-source" | "module-source" | "intermediate" | "secret-source" | "sink")
+/**
+ * Dead-code issue kind linked to a security candidate.
+ */
+export type SecurityDeadCodeKind = ("unused-file" | "unused-export")
+/**
+ * How strongly the untrusted-source signal is associated with the sink, a
+ * structured discriminator so a consumer can tier candidates without parsing
+ * the human `evidence` prose. Present only when
+ * [`SecurityReachability::reachable_from_untrusted_source`] is true. Neither
+ * value proves exploitability; both are ranking signals (issue #885 doctrine:
+ * rank, never gate).
+ */
+export type TaintConfidence = ("arg-level" | "module-level")
+/**
+ * Runtime coverage state for the function enclosing a security sink.
+ * This is production-observation evidence, not an exploitability verdict.
+ */
+export type SecurityRuntimeState = ("runtime-hot" | "runtime-cold" | "never-executed" | "low-traffic" | "coverage-unavailable" | "runtime-unknown")
+/**
+ * Defensive control family detected on a source to sink path.
+ */
+export type SecurityControlKind = ("sanitization" | "validation" | "authentication" | "authorization")
 /**
  * Discriminator value for [`CodeClimateIssue::kind`].
  */
@@ -4168,6 +4214,46 @@ allow: string[]
  */
 allow_type_only?: string[]
 }
+/**
+ * `fallow workspaces --format json` envelope.
+ */
+export interface WorkspacesOutput {
+/**
+ * Number of workspace package entries in `workspaces`.
+ */
+workspace_count: number
+/**
+ * Workspace packages discovered from package manager and tsconfig workspace
+ * declarations. Paths are project-root-relative and use forward slashes.
+ */
+workspaces: WorkspaceInfo[]
+/**
+ * Workspace discovery diagnostics produced while reading workspace
+ * declarations. Present for compatibility with the current wire contract,
+ * even when empty.
+ */
+workspace_diagnostics: WorkspaceDiagnostic[]
+}
+/**
+ * One workspace package emitted by `fallow workspaces --format json`.
+ */
+export interface WorkspaceInfo {
+/**
+ * Package name from the workspace package.json. This is the value accepted
+ * by `--workspace <name>`.
+ */
+name: string
+/**
+ * Project-root-relative path to the workspace directory, normalized to
+ * forward slashes for cross-platform JSON consumers.
+ */
+path: string
+/**
+ * Whether the package is a generated or platform-specific dependency
+ * package rather than a hand-authored workspace.
+ */
+is_internal_dependency: boolean
+}
 /**
  * Envelope emitted by `fallow health --format json` (plus the `health` block
  * inside the combined and audit envelopes).
@@ -4791,15 +4877,27 @@ git_sha?: (string | null)
 timestamp: string
 }
 /**
- * The `fallow security --format json` envelope. `security_findings` is the
- * unique required field used for untagged narrowing in `FallowOutput`.
+ * The `fallow security --format json` envelope. `FallowOutput` discriminates it
+ * by the `kind: "security"` tag; the optional `gate` block is additive and is
+ * not part of that discrimination.
  */
 export interface SecurityOutput {
 schema_version: SecuritySchemaVersion
+/**
+ * Gate verdict, present only when `--gate <mode>` was set (issue #886).
+ * Emitted on pass too (`verdict: "pass"`, `new_count: 0`) so consumers
+ * distinguish "gate ran and passed" from "gate did not run" (absent).
+ */
+gate?: (SecurityGate | null)
 /**
  * Security candidates. Paths are project-root-relative, forward-slash.
  */
 security_findings: SecurityFinding[]
+/**
+ * Opt-in attack-surface inventory from untrusted entry points to reachable
+ * sinks. Present only when `--surface` was requested.
+ */
+attack_surface?: (SecurityAttackSurfaceEntry[] | null)
 /**
  * In-band blind spot: number of `"use client"` files whose transitive
  * import cone contains a dynamic `import()` the reachability BFS could not
@@ -4815,6 +4913,18 @@ unresolved_edge_files: number
  */
 unresolved_callee_sites: number
 }
+/**
+ * The `gate` block on `SecurityOutput`, present only when `--gate <mode>` ran.
+ * Invariant: `verdict == Fail  IFF  exit code 8  IFF  new_count > 0`.
+ */
+export interface SecurityGate {
+mode: SecurityGateMode
+verdict: SecurityGateVerdict
+/**
+ * Number of candidates introduced in the changed lines.
+ */
+new_count: number
+}
 /**
  * A local security CANDIDATE for downstream agent verification, NOT a verified
  * vulnerability. Emitted only by `fallow security`, never under bare `fallow`
@@ -4823,6 +4933,14 @@ unresolved_callee_sites: number
  * (its hops and length) is the only honest signal.
  */
 export interface SecurityFinding {
+/**
+ * Stable per-finding correlation id, identical across runs for the same
+ * rule + anchor path + line. An autonomous agent that triaged this
+ * candidate on a prior run uses it to correlate the candidate after a
+ * rebase. Equal to the SARIF `partialFingerprints` value for the same
+ * finding (one shared helper computes both).
+ */
+finding_id: string
 kind: SecurityFindingKind
 /**
  * The catalogue category id (e.g. `"dangerous-html"`). `None` for
@@ -4862,6 +4980,7 @@ evidence: string
  * `ClientServerLeak`. Skipped from JSON when `false` for output stability.
  */
 source_backed?: boolean
+severity: SecuritySeverity
 /**
  * Structural import-hop trace from the client boundary to the secret source.
  * The hop count is the uncalibrated signal; fallow does not prove the path
@@ -4876,12 +4995,37 @@ trace: TraceHop[]
  */
 actions: IssueAction[]
 /**
- * Graph-derived reachability ranking signal (issue #860). `None` until the
- * post-detection ranking pass fills it; additive on the wire (skipped when
- * absent). Drives the order findings are emitted in: candidates reachable
- * from a runtime entry point with a wider blast radius sort first.
+ * Dead-code cross-link when the same sink candidate sits in code fallow also
+ * reports as removable. Agents should verify the dead-code finding and delete
+ * the code instead of hardening the sink when deletion is safe.
+ */
+dead_code?: (SecurityDeadCodeContext | null)
+/**
+ * Graph-derived reachability ranking signal (issues #860 and #885). `None`
+ * until the post-detection ranking pass fills it; additive on the wire
+ * (skipped when absent). Drives the order findings are emitted in:
+ * runtime-reachable candidates sort first, followed by source-backed and
+ * source-reachable candidates, then wider blast radius.
  */
 reachability?: (SecurityReachability | null)
+candidate: SecurityCandidate
+/**
+ * Source-to-sink taint-flow triple, present only when an untrusted source
+ * is import-reachable to this sink. Absent (skipped) otherwise.
+ */
+taint_flow?: (SecurityTaintFlow | null)
+/**
+ * Production runtime coverage context for the function enclosing this
+ * security sink. Present only when `fallow security --runtime-coverage`
+ * runs and the candidate is a `tainted-sink`.
+ */
+runtime?: (SecurityRuntimeContext | null)
+/**
+ * Internal projection used by `fallow security --surface`. The CLI strips
+ * this from per-finding JSON and promotes it to the top-level
+ * `attack_surface` field only when requested.
+ */
+attack_surface?: (SecurityAttackSurfaceEntry | null)
 }
 /**
  * One hop in a security finding's structural trace. Stored as an absolute path
@@ -4905,11 +5049,31 @@ line: number
 col: number
 role: TraceHopRole
 }
+/**
+ * Dead-code cross-link attached to a security candidate when fallow's dead-code
+ * pass reports the same anchor as removable code.
+ */
+export interface SecurityDeadCodeContext {
+kind: SecurityDeadCodeKind
+/**
+ * Unused export name when `kind` is `unused-export`.
+ */
+export_name?: (string | null)
+/**
+ * Dead-code finding line when available.
+ */
+line?: (number | null)
+/**
+ * Agent-facing guidance for deciding between deletion and hardening.
+ */
+guidance: string
+}
 /**
  * Graph-derived reachability ranking signal for a security candidate. Computed
- * from the EXISTING module graph (runtime reachability + reverse-dep fan-in)
- * after detection, never proven exploitable. Used to surface candidates that
- * sit on a request/runtime-reachable surface above isolated helpers or scripts.
+ * from the existing module graph after detection, never proven exploitable.
+ * Used to surface candidates that sit on a request/runtime-reachable surface,
+ * receive same-module source evidence, or are import-reachable from an
+ * untrusted-source module above isolated helpers or scripts.
  *
  * This is a relative-ordering signal, NOT a `confidence` or `signal_strength`
  * score: fallow does not prove the path is exploitable.
@@ -4922,6 +5086,32 @@ export interface SecurityReachability {
  * only from test entry points does not count.
  */
 reachable_from_entry: boolean
+/**
+ * Whether the anchor module is reachable over value imports from a module
+ * that reads a known untrusted input source. Module-level only: this does
+ * not prove a specific source value reaches the sink argument.
+ */
+reachable_from_untrusted_source?: boolean
+/**
+ * Structured tier of the untrusted-source association: `arg-level` when the
+ * sink argument traces to a same-module source read (strong), `module-level`
+ * when only the module is import-reachable from a source (weak). Present
+ * exactly when `reachable_from_untrusted_source` is true, so a consumer can
+ * separate strong from weak candidates from this field alone without parsing
+ * the `evidence` string. Not an exploitability proof.
+ */
+taint_confidence?: (TaintConfidence | null)
+/**
+ * Number of value-import hops from the untrusted-source module to the sink
+ * module when `reachable_from_untrusted_source` is true.
+ */
+untrusted_source_hop_count?: (number | null)
+/**
+ * Module-level import path from the untrusted-source module to the sink
+ * anchor. Empty when no source module reaches this candidate. The path is a
+ * ranking explanation, not a value-flow proof.
+ */
+untrusted_source_trace?: TraceHop[]
 /**
  * Number of distinct modules that transitively depend on the anchor module
  * (fan-in via the graph's reverse-dependency index). A higher value means a
@@ -4936,6 +5126,257 @@ blast_radius: number
  */
 crosses_boundary: boolean
 }
+/**
+ * An agent-actionable candidate record on a [`SecurityFinding`]. fallow fills
+ * `source_kind`, `sink`, and `boundary`. The exploitability IMPACT is
+ * deliberately NOT a field: `severity` on the parent finding is only a
+ * review-priority tier, while deciding exploitability remains the consuming
+ * agent's job. A perpetually-null `impact` key would only train consumers to
+ * ignore it. The agent reads this record, then writes its own impact verdict
+ * downstream.
+ */
+export interface SecurityCandidate {
+/**
+ * The kind of untrusted input that reaches the sink, as a stable catalogue
+ * source id (`"http-request-input"`, `"process-env"`, `"process-argv"`,
+ * `"message-event-data"`, `"location-input"`, ...). `None`/absent when no
+ * untrusted source was matched (always `None` for `client-server-leak`).
+ * This is an OPEN string set, driven by the data-driven source catalogue; a
+ * consumer should treat an unknown id as "untrusted source of unknown kind"
+ * and never drop the candidate on that basis.
+ */
+source_kind?: (string | null)
+sink: SecurityCandidateSink
+boundary: SecurityCandidateBoundary
+/**
+ * Network-destination context, present only on `secret-to-network` (#890)
+ * candidates: the host the secret-bearing call targets, so an agent can
+ * triage exfil from intended auth. Absent for every other category.
+ */
+network?: (SecurityNetworkContext | null)
+}
+/**
+ * The sink slot of a [`SecurityCandidate`]: a self-contained description of the
+ * matched sink site. Echoes the finding's own span (`path`/`line`/`col`) plus
+ * the catalogue `category`/`cwe` and the captured `callee`, so an agent can act
+ * on `candidate.sink` in isolation (e.g. after fanning a finding out to a
+ * sub-agent) without reading the parent finding.
+ */
+export interface SecurityCandidateSink {
+/**
+ * File of the sink site. Absolute internally; JSON strips the project root
+ * via `serde_path::serialize`.
+ */
+path: string
+/**
+ * 1-based line of the sink site.
+ */
+line: number
+/**
+ * 0-based byte column of the sink site.
+ */
+col: number
+/**
+ * Catalogue category id of the sink (e.g. `"dangerous-html"`). `None` for
+ * `client-server-leak`.
+ */
+category?: (string | null)
+/**
+ * CWE number declared by the catalogue entry. `None` for
+ * `client-server-leak`; never fabricated beyond the catalogue's value.
+ */
+cwe?: (number | null)
+/**
+ * The sink callee (the dangerous function or member path, e.g.
+ * `"el.innerHTML"`, `"child_process.exec"`) captured by the catalogue match.
+ * `None` for `client-server-leak` and matches that name no callee.
+ */
+callee?: (string | null)
+}
+/**
+ * The boundary slot of a [`SecurityCandidate`]: which structural boundaries the
+ * candidate's flow crosses. A flow that crosses a client/server or module
+ * boundary is a stronger review target than a self-contained one; the boundary
+ * is fallow's structural signal over a pure source-sink match.
+ *
+ * Two further boundary kinds are RESERVED for a follow-up and are deliberately
+ * absent here rather than emitted as always-false: `export_visibility` (is the
+ * sink on a publicly-exported symbol?) and a package boundary (does the flow
+ * cross an npm-package edge?). Both need new graph derivation that does not
+ * exist today; emitting them as `false` would misreport "we checked and it does
+ * not cross" when fallow has not checked at all.
+ */
+export interface SecurityCandidateBoundary {
+/**
+ * Whether the finding crosses a client/server boundary (a `"use client"`
+ * file appears in the trace). True only for `client-server-leak` today;
+ * `tainted-sink` candidates carry no client/server marker.
+ */
+client_server: boolean
+/**
+ * Whether an untrusted source reaches the sink across one or more
+ * value-import (module) hops. Derived from the reachability hop count.
+ */
+cross_module: boolean
+/**
+ * The architecture-zone crossing when the anchor participates in a declared
+ * boundary-rule violation in the same run. `None` when it crosses no
+ * declared zone boundary.
+ */
+architecture_zone?: (SecurityZoneCrossing | null)
+}
+/**
+ * A declared architecture-zone crossing, recovered by correlating a finding's
+ * anchor against the run's architecture-boundary violations.
+ */
+export interface SecurityZoneCrossing {
+/**
+ * Zone the importing side belongs to.
+ */
+from: string
+/**
+ * Zone the imported side belongs to.
+ */
+to: string
+}
+/**
+ * Network-destination context for a `secret-to-network` candidate (#890): where
+ * the secret-bearing network call sends its data. Present only on
+ * network-category candidates. A consuming agent uses it to triage exfil
+ * (dynamic / untrusted destination) from intended auth (a literal provider
+ * host) without re-reading source.
+ */
+export interface SecurityNetworkContext {
+/**
+ * The network call's destination as a static URL string literal, or absent
+ * when the destination is DYNAMIC (not a literal). A dynamic destination is
+ * the higher-signal exfil case; a literal provider host is usually intended
+ * auth.
+ */
+destination?: (string | null)
+}
+/**
+ * A source-to-sink taint-flow triple, emitted only when an untrusted source is
+ * import-reachable to the sink (`reachability.reachable_from_untrusted_source`).
+ * The `{ source, sink, path }` shape matches the model agent SAST tooling
+ * expects (cf. Semgrep `taint_source` / `taint_sink`, SARIF `threadFlows`).
+ */
+export interface SecurityTaintFlow {
+source: TaintEndpoint
+sink: TaintEndpoint
+path: TaintPath
+}
+/**
+ * One endpoint (source or sink node) of a [`SecurityTaintFlow`].
+ */
+export interface TaintEndpoint {
+/**
+ * File of the endpoint. Absolute internally; JSON strips the project root.
+ */
+path: string
+/**
+ * 1-based line of the endpoint.
+ */
+line: number
+/**
+ * 0-based byte column of the endpoint.
+ */
+col: number
+}
+/**
+ * Compact taint-flow path shape. The ordered per-hop trace is NOT duplicated
+ * here: it lives on [`SecurityReachability::untrusted_source_trace`]. This
+ * carries only the flow's structural summary (intra-module flow plus the
+ * cross-module hop count) so consumers do not parse two copies of the hops.
+ */
+export interface TaintPath {
+/**
+ * Whether the source and sink sit in the same module (no import hop between
+ * them); the source-to-sink association is intra-module.
+ */
+intra_module: boolean
+/**
+ * Number of value-import hops from the untrusted-source module to the sink
+ * module. Zero for an intra-module flow.
+ */
+cross_module_hops: number
+}
+/**
+ * Runtime coverage context attached to a security candidate when
+ * `fallow security --runtime-coverage` is supplied.
+ */
+export interface SecurityRuntimeContext {
+state: SecurityRuntimeState
+/**
+ * Enclosing function name from static extraction.
+ */
+function: string
+/**
+ * 1-based line where the enclosing function starts.
+ */
+line: number
+/**
+ * Observed invocation count when the runtime report provides it.
+ */
+invocations?: (number | null)
+/**
+ * Runtime coverage stable function id, when available.
+ */
+stable_id?: (string | null)
+/**
+ * Short candidate-framed explanation of the runtime evidence.
+ */
+evidence?: (string | null)
+}
+/**
+ * One untrusted entry to reachable sink path for `fallow security --surface`.
+ */
+export interface SecurityAttackSurfaceEntry {
+source: TaintEndpoint
+sink: SecurityCandidateSink
+/**
+ * Ordered source to sink path. Same shape as the reachability trace so
+ * consumers can reuse existing path handling.
+ */
+path: TraceHop[]
+defensive_boundary: SecurityDefensiveBoundary
+}
+/**
+ * Agent-facing defensive-boundary verification context for one surface path.
+ */
+export interface SecurityDefensiveBoundary {
+/**
+ * Known controls detected along this path.
+ */
+controls: SecurityDefensiveControl[]
+/**
+ * Verification question for the consuming agent. It is a prompt, not a
+ * missing-guard verdict.
+ */
+verification_prompt: string
+}
+/**
+ * Defensive control found on an attack-surface path.
+ */
+export interface SecurityDefensiveControl {
+kind: SecurityControlKind
+/**
+ * File of the control site. Absolute internally; JSON strips the project root.
+ */
+path: string
+/**
+ * 1-based line of the control site.
+ */
+line: number
+/**
+ * 0-based byte column of the control site.
+ */
+col: number
+/**
+ * Flattened callee path or a stable synthetic guard name.
+ */
+callee: string
+}
 /**
  * Bare `fallow --format json` envelope.
  */