@clear-capabilities/agentic-security-scanner 0.185.0 → 0.186.1

package/src/language/nix-option-types.js

@@ -0,0 +1,170 @@
+// Declared option types, read from the module sources that are in scope.
+//
+// A NixOS or Home Manager option is declared with `mkOption { type = ...; }`
+// (or `mkEnableOption`, `mkPackageOption`). The module system checks a value
+// against that type before the module's `config` is used, so the TYPE bounds
+// what a reference to the option can contain, whatever the name suggests:
+//
+//   bool, int, ints.*, port, float, number   digits, `0`/`1`, a sign or a dot
+//   package, shellPackage                    a store path (`/nix/store/<hash>-<name>`),
+//                                            whose name part is restricted by Nix to
+//                                            [A-Za-z0-9+._?=-]
+//   enum [ "a" "b" ]                         one of the listed literals
+//   nullOr T, either A B, uniq T             only when every member is itself bounded
+//
+// `str`, `path`, `lines`, `attrs`, `listOf`, `submodule`, an unknown or computed
+// type are all UNBOUNDED here: they can carry any characters, so nothing is
+// inferred from them.
+//
+// Two consumers use the answer in opposite directions, and both are sound for
+// the same reason:
+//   * the script-injection analysis treats a reference to a bounded option as
+//     a constant, because no value of that type contains a shell metacharacter;
+//   * the secret analysis does not treat a reference to a bounded option as a
+//     credential, because a bool, a number, a package path or a choice among
+//     listed words does not hold a secret, whatever the option is called
+//     (`cacheCredentials`, `forwardPass`, `wheelNeedsPassword`).
+//
+// Only options DECLARED in the files handed to the analyzer are known. An
+// option declared elsewhere (upstream NixOS) has no entry, so it keeps the
+// previous behaviour: unknown stays conservative.
+
+const unparen = (n) => { let x = n; while (x && x.type === 'paren') x = x.expr; return x; };
+const segName = (s) => (s && s.kind === 'static' ? s.name : null);
+const attrKey = (path) => (path || []).map(segName);
+
+const BOUNDED_LEAF = new Set(['bool', 'int', 'float', 'number', 'port', 'package', 'shellPackage', 'unsigned', 'positive', 'u8', 'u16', 'u32', 's8', 's16', 's32', 'between']);
+const BOUNDED_NAMESPACES = new Set(['ints', 'numbers']);
+const SAFE_ENUM_MEMBER = /^[A-Za-z0-9_.+-]*$/;
+
+function flatten(n) {
+  const args = []; let fn = unparen(n);
+  while (fn && fn.type === 'app') { args.unshift(fn.arg); fn = unparen(fn.fn); }
+  return { fn, args };
+}
+
+function calleeName(fn) {
+  const f = unparen(fn);
+  if (!f) return null;
+  if (f.type === 'ident') return f.name;
+  if (f.type === 'select') { const segs = f.attrpath.map(segName); return segs[segs.length - 1] || null; }
+  return null;
+}
+
+function selectSegments(n) {
+  const segs = n.attrpath.map(segName);
+  return segs.every((s) => s !== null) ? segs : null;
+}
+
+/** Classify a `type = ...` expression. Returns { kind, bounded }. */
+export function classifyOptionType(expr, depth = 0) {
+  const n = unparen(expr);
+  if (!n || depth > 8) return { kind: 'unknown', bounded: false };
+  if (n.type === 'ident') return { kind: n.name, bounded: BOUNDED_LEAF.has(n.name) };
+  if (n.type === 'select') {
+    const segs = selectSegments(n);
+    if (!segs) return { kind: 'unknown', bounded: false };
+    const last = segs[segs.length - 1];
+    if (segs.some((s) => BOUNDED_NAMESPACES.has(s))) return { kind: `${segs.slice(-2).join('.')}`, bounded: true };
+    return { kind: last, bounded: BOUNDED_LEAF.has(last) };
+  }
+  if (n.type === 'app') {
+    const { fn, args } = flatten(n);
+    const name = calleeName(fn);
+    const fnSel = unparen(fn);
+    if (fnSel && fnSel.type === 'select') {
+      const segs = selectSegments(fnSel);
+      if (segs && segs.some((s) => BOUNDED_NAMESPACES.has(s))) return { kind: segs.slice(-2).join('.'), bounded: true };
+    }
+    if (name === 'nullOr' || name === 'uniq' || name === 'unique') return args[0] ? classifyOptionType(args[0], depth + 1) : { kind: name, bounded: false };
+    if (name === 'either') {
+      const parts = args.slice(0, 2).map((a) => classifyOptionType(a, depth + 1));
+      return { kind: 'either', bounded: parts.length === 2 && parts.every((p) => p.bounded) };
+    }
+    if (name === 'enum') {
+      const list = unparen(args[0]);
+      if (list && list.type === 'list') {
+        const members = list.items.map((i) => unparen(i));
+        const ok = members.length > 0 && members.every((m) => m && m.type === 'string' && !m.interpolated && SAFE_ENUM_MEMBER.test(m.literal || ''));
+        return { kind: 'enum', bounded: ok };
+      }
+      return { kind: 'enum', bounded: false };
+    }
+    return { kind: name || 'unknown', bounded: false };
+  }
+  return { kind: 'unknown', bounded: false };
+}
+
+function declarationOf(valueNode) {
+  const v = unparen(valueNode);
+  if (!v || v.type !== 'app') return null;
+  const { fn, args } = flatten(v);
+  const name = calleeName(fn);
+  if (name === 'mkEnableOption') return { kind: 'bool', bounded: true };
+  if (name === 'mkPackageOption' || name === 'mkPackageOptionMD') return { kind: 'package', bounded: true };
+  if (name === 'mkOption') {
+    const a = unparen(args[0]);
+    if (!a || a.type !== 'attrset') return { kind: 'unknown', bounded: false };
+    for (const b of a.bindings || []) {
+      if (b.kind !== 'attr') continue;
+      const k = attrKey(b.path);
+      if (k.length === 1 && k[0] === 'type') return classifyOptionType(b.value);
+    }
+    return { kind: 'untyped', bounded: false };
+  }
+  return null;
+}
+
+function record(index, key, decl) {
+  const prev = index.get(key);
+  // two declarations of one option: bounded only if every declaration is
+  index.set(key, prev ? { kind: prev.kind, bounded: prev.bounded && decl.bounded } : decl);
+}
+
+function collect(node, prefix, index, depth) {
+  if (!node || typeof node !== 'object' || depth > 200) return;
+  if (Array.isArray(node)) { for (const x of node) collect(x, prefix, index, depth + 1); return; }
+  if (node.type === 'attrset') {
+    for (const b of node.bindings || []) {
+      if (b.kind !== 'attr' || !b.value) continue;
+      const keys = attrKey(b.path);
+      if (keys.some((k) => k === null)) { collect(b.value, null, index, depth + 1); continue; }
+      let full = null;
+      if (prefix !== null) full = [...prefix, ...keys];
+      else if (keys[0] === 'options') full = keys.slice(1);
+      if (full === null) { collect(b.value, null, index, depth + 1); continue; }
+      const decl = full.length ? declarationOf(b.value) : null;
+      if (decl) { record(index, full.join('.'), decl); continue; }
+      const v = unparen(b.value);
+      if (v && v.type === 'attrset') collect(v, full, index, depth + 1);
+      else collect(b.value, null, index, depth + 1);
+    }
+    return;
+  }
+  for (const [k, c] of Object.entries(node)) {
+    if (k === 'span' || k === 'loc') continue;
+    if (c && typeof c === 'object') collect(c, prefix === null ? null : null, index, depth + 1);
+  }
+}
+
+/**
+ * Index every option declared in the parsed files: dotted path -> { kind, bounded }.
+ * `parsed` is an iterable of ASTs.
+ */
+export function buildOptionTypeIndex(parsed) {
+  const index = new Map();
+  for (const ast of parsed) collect(ast, null, index, 0);
+  return index;
+}
+
+/**
+ * Is the option behind an origin detail (`option config.a.b.c`) declared with a
+ * bounded type? Returns the declaration, or null when it is unknown or unbounded.
+ */
+export function boundedOptionFor(index, detail) {
+  if (!index || typeof detail !== 'string') return null;
+  const m = /^option (?:config|osConfig)\.(.+)$/.exec(detail);
+  if (!m) return null;
+  const d = index.get(m[1]);
+  return d && d.bounded ? d : null;
+}

package/src/language/nix-script-taint.js

@@ -22,6 +22,7 @@
 import { parseNix, makeLocator } from './nix-parser.js';
 import { resolveImportPath } from './nix-ir.js';
 import { isLanguageExcludedPath } from './discovery.js';
+import { buildOptionTypeIndex } from './nix-option-types.js';
 
 export const NIX_SCRIPT_VERSION = 'nix-script-taint/1';
 const PH = '';
@@ -44,7 +45,7 @@ const TRUSTED_PARAMS = new Set(['pkgs', 'lib', 'stdenv', 'self', 'inputs', 'syst
 const CONFIG_PARAMS = new Set(['config', 'options', 'osConfig']);
 const RUNTIME_SECRET_DIRS = /^\/(?:run\/(?:secrets|agenix|credentials|keys)|var\/lib\/(?:secrets|credentials)|etc\/secrets)\b/;
 const SECRET_NAME = /(?:pass(?:word|wd|phrase)?|psk|secret|token|api_?key|private_?key|credential|auth_?key|client_?secret|bearer|cookie|session_?key)/i;
-const PATHISH_TAIL = /(?:file|path|dir|directory|package|pkg|enable|port|user|group|name)$/i;
+const PATHISH_TAIL = /(?:file|path|dir|directory|package|pkg|enable|port|user|group|name|scripts?|commands?|cmds?)$/i;
 const FETCHERS = new Set(['fetchurl', 'fetchTarball', 'fetchGit', 'fetchzip', 'fetchFromGitHub', 'fetchgit', 'fetchTree', 'fetchClosure', 'fetchMercurial', 'fetchpatch']);
 const FS_CMDS = new Set(['rm', 'rmdir', 'mv', 'cp', 'chmod', 'chown', 'chgrp', 'mkdir', 'ln', 'touch', 'tee', 'dd', 'install', 'truncate', 'shred', 'unlink', 'rsync', 'tar', 'unzip', 'cat', 'sed', 'find', 'mount', 'umount']);
 const NET_CMDS = new Set(['curl', 'wget', 'nc', 'ncat', 'netcat', 'ssh', 'scp', 'sftp', 'rsync', 'ftp', 'telnet', 'socat', 'git', 'psql', 'mysql', 'redis-cli', 'mongo', 'aws', 'gsutil']);
@@ -58,7 +59,16 @@ const spanOf = (n) => (n && n.span ? n.span : null);
 // ── files ────────────────────────────────────────────────────────────────────
 class Workspace {
   constructor(files) {
-    this.files = files; this.parsed = new Map();
+    this.files = files; this.parsed = new Map(); this._optionTypes = null;
+  }
+  /** Declared option types across every file in scope (see nix-option-types.js). Built once. */
+  optionTypes() {
+    if (!this._optionTypes) {
+      const asts = [];
+      for (const f of Object.keys(this.files)) { const r = this.parse(f); if (r && r.ast) asts.push(r.ast); }
+      this._optionTypes = buildOptionTypeIndex(asts);
+    }
+    return this._optionTypes;
   }
   parse(file) {
     if (this.parsed.has(file)) return this.parsed.get(file);
@@ -227,7 +237,38 @@ class Evaluator {
     return { origins: [mkOrigin('argument', `function argument "${name}"`, hops)], protection: null };
   }
 
-  eval(expr, env, depth = 0) {
+  /**
+   * An option reference whose DECLARED type bounds its value (bool, int, port, package, a listed enum) cannot carry
+   * a shell metacharacter or a credential, whatever its name suggests, so it is a constant. An option declared out of
+   * scope keeps its origin, except that the module-system convention for a package option (`package`, `finalPackage`,
+   * `fooPackage`) is a store path.
+   */
+  refine(r) {
+    if (!r || !r.origins.some((o) => o.kind === 'configuration' || o.kind === 'secret')) return r;
+    const idx = this.res.ws.optionTypes();
+    let changed = false;
+    const origins = r.origins.map((o) => {
+      if (o.kind !== 'configuration' && o.kind !== 'secret') return o;
+      const m = /^(?:option|module parameter) (?:config|osConfig)\.(.+)$/.exec(o.detail);
+      if (!m) return o;
+      const decl = idx.get(m[1]);
+      if (decl) {
+        if (!decl.bounded) return o;
+        changed = true;
+        return mkOrigin('constant', `${o.detail} (declared ${decl.kind})`, o.chain);
+      }
+      if (/^(?:package|finalPackage|[a-z][A-Za-z0-9]*Package)$/.test(m[1].split('.').pop())) {
+        changed = true;
+        return mkOrigin('store', `${o.detail} (a package option)`, o.chain);
+      }
+      return o;
+    });
+    return changed ? { ...r, origins: dedupe(origins) } : r;
+  }
+
+  eval(expr, env, depth = 0) { return this.refine(this.evalRaw(expr, env, depth)); }
+
+  evalRaw(expr, env, depth = 0) {
     const n = unparen(expr);
     if (!n || depth > MAX_DEPTH) return this.unknown('depth limit');
     switch (n.type) {
@@ -364,6 +405,8 @@ class Evaluator {
       const r = rest.length ? this.combine(rest) : this.constant('empty');
       return { ...r, origins: dedupe([...(sep ? sep.origins : []), ...r.origins]) };
     }
+    // a hex digest, whatever it was computed from
+    if (name === 'hashString' || name === 'hashFile') return this.constant(`${name} (hex digest)`);
     if (name === 'optionalString' || name === 'optional' || name === 'optionals') return args[1] ? this.eval(args[1], env, depth + 1) : this.constant('empty');
     if (name === 'getExe' || name === 'getBin' || name === 'getLib' || name === 'getDev' || name === 'getExe\'') return { origins: [mkOrigin('store', `${name} (store path)`)], protection: null };
     if (name === 'writeText' || name === 'writeTextFile' || name === 'writeShellScript' || name === 'writeShellScriptBin' || name === 'writeScript' || name === 'writeScriptBin' || name === 'runCommand' || name === 'mkDerivation') return { origins: [mkOrigin('store', `${name} output (store path)`)], protection: null };

package/src/language/nix-secrets.js

@@ -217,7 +217,8 @@ class Walker {
       }
       case 'app': {
         if (!asFn) this.inspectApp(file, node, env, path);
-        this.visit(file, node.fn, env, path, depth + 1, true); this.visit(file, node.arg, env, path, depth + 1, false); return;
+        this.visit(file, node.fn, env, path, depth + 1, true);
+        this.visit(file, this.withoutOptionDocs(node), env, path, depth + 1, false); return;
       }
       case 'string': {
         if (!node.interpolated) { for (const [label, re, sev] of TOKEN_FORMATS) if (re.test(node.literal || '')) { /* reported through its binding when it has one; bare strings: */ if (!this.stringSeen(file, node)) this.emit('nix-secret-plaintext', { ...this.at(file, node.span), file, severity: sev, exposure: 'plaintext-source', description: `A ${label} is written as a literal (value redacted).`, source: { kind: 'literal', file, line: node.span.startLine }, destination: { kind: 'source', label: 'Nix source' }, evidence: { ...redact(node.literal), format: label }, originalLocation: node.span, chain: [hop(file, node.span, `literal ${label}`)].filter(Boolean), origins: [mkOrigin('secret', `literal ${label}`)] }); } }
@@ -229,10 +230,27 @@ class Walker {
         if (node.items) for (const it of node.items) this.visit(file, it, env, path, depth + 1, false);
     }
   }
+  /**
+   * The argument of `mkOption { ... }` without its documentation attributes. `example`, `description` and
+   * `defaultText` are rendered into the manual, never into the configuration, so a credential-shaped literal
+   * there is an illustration. `default` is NOT documentation: it is the value the option takes.
+   */
+  withoutOptionDocs(appNode) {
+    const arg = appNode.arg;
+    const { fn } = this.ev.flatten(appNode);
+    const name = this.ev.calleeOf(fn).name;
+    const a = unparen(arg);
+    if (name !== 'mkOption' || !a || a.type !== 'attrset') return arg;
+    const DOC = new Set(['example', 'description', 'defaultText', 'longDescription', 'relatedPackages']);
+    return { ...a, bindings: a.bindings.filter((b) => !(b.kind === 'attr' && DOC.has(attrKey(b.path)[0]))) };
+  }
   stringSeen(file, node) { const k = `${file}:${node.start}`; if (this.scriptKeys.has(k)) return true; this.scriptKeys.add(k); return false; }
 
   inspectBinding(file, full, value, bspan, env) {
-    const v = unparen(value);
+    let v = unparen(value);
+    // `x = let ... in { ... }` / `with ...; { ... }` is an attribute SET, not a scalar: a credential name on the
+    // binding (a service called pass-secret-service) says nothing about a set's members, which are visited on their own
+    for (let guard = 0; v && (v.type === 'let' || v.type === 'with' || v.type === 'assert') && guard < 20; guard++) v = unparen(v.body);
     const last = full[full.length - 1];
     const dest = destOf(full);
     const sname = secretName(last);

package/src/lineage/CLAUDE.md

@@ -1274,7 +1274,8 @@ restricts characters); the projection refuses them, but the graph contract itsel
 | Module | Responsibility |
 |---|---|
 | `path-predicates.js` | Branch conditions for a witness. A node is guarded by (branch, polarity) only when that arm dominates it and has the branch as its only predecessor, so a node after a join is guarded by neither arm. Conditions are kept as bounded DNF (`a || b` is two distinct alternatives), variables are keyed by (call frame, name, reaching-definition versions), and a callee parameter is tied to the caller argument only through an explicit call binding. Both arms of one branch on one witness are reported (`mutually-exclusive-branches`), never conjoined; inside a loop with a per-iteration definition the answer is `unknown`. Evaluation reuses `numeric-domain.js` intervals through `symbolic-exec.js` `assume`, plus equality on constants and boolean atoms. Results: `feasible-model`, `infeasible-under-model`, `unknown`, `unsupported` (reflective dispatch anywhere in a frame's function, or no CFG), `timeout`; each with semantics version, reasons, limitations. Satisfiability never implies exploitability, and `infeasible-under-model` is relative to the stated limits. |
-| `smt-orchestrator.js` | The optional solver path. `checkWithSolver` is awaited, deadline-bounded, cancellable (caller `AbortSignal` plus its own deadline abort the solver's signal) and never throws; a late solver settlement is swallowed. `noSolver` is the default stub (`unsupported`). A solver is consulted only when the abstract answer is `unknown`, and the abstract answer stays on the result. No solver or dependency ships. |
+| `smt-orchestrator.js` | The optional solver path. `checkWithSolver` is awaited, deadline-bounded, cancellable (caller `AbortSignal` plus its own deadline abort the solver's signal) and never throws; a late solver settlement is swallowed. `noSolver` is the default stub (`unsupported`). A solver is consulted when the abstract answer is `unknown`, or `feasible-model` with `consultOnFeasible` (default: on only when `AGENTIC_SECURITY_LINEAGE_SMT=z3`); the abstract answer stays on the result, and on a feasible answer only a solver `unsat` changes it. `resolveSolver` picks an explicit solver, else the z3 backend when the env switch is `z3`, else `noSolver`. An `unsat` over branch arms in a loop is not trusted. |
+| `smt-z3-backend.js` | The real backend on the optional `z3-solver`. Lazy dynamic import (variable specifier, build flag `-e z3-solver`), so a default scan never loads it; a missing or failing package, or a context that ignores its timeout, is `unsupported`, never a crash and never `unsat`. `encodeProblem` is the verified encoding (Real sort, `v0..vN` renaming, constants asserted, opaque predicate = no constraint); an inexpressible problem is `unknown` with an `encoding-unverified:*` reason, and a `sat` that used an opaque predicate is `unknown`. Per-query timeout, Z3 memory cap, fixed seed, one query at a time, definitive answers cached by SMT-LIB text. Reached only from the async path-evidence entry points; the synchronous graph build never calls it. Suite: `test/lineage/smt-z3-backend.test.js` (real-solver tests skip loudly where z3 is absent). |
 | `control-credit.js` | A control earns credit on a witness only for the matching sink family (catalog `appliesTo` vs the sink CWE family), on the value version the sink reads (reassignment or a merge with another definition refuses), and when nothing later on the witness reverses it (`_reversedOnPath`). A parameterized SQL call earns SQL credit only for values bound after a literal placeholder query text. A bare callee name shared by entries that disagree on families is ambiguous and not credited. An unrecognized call that widened the value is opaque: `unknown`. Credits say `semanticsProof: false`: dominance and catalog family are evidence, not proof of sanitizer semantics. `assessAllPathsProtectedWithControls` feeds real control states into `witness-selection.js` `assessAllPathsProtected`, lists `infeasible-under-model` paths it excluded, keeps `unknown`/`timeout` paths relevant, and accepts an `abstractControlProof` (dominating, single-reaching-definition control, intraprocedural) only when no enumerated path refutes. |
 | `path-evidence.js` | Assembles per-path evidence, summarizes a flow group (alternatives stay distinct, aggregate control state is the worst over relevant paths) and `buildControlEvidence`, which fills the witness bundle `controlEvidence` slot (`feasible`/`infeasible`/`unknown` plus the precise result in `detail`). |
 

package/src/lineage/smt-orchestrator.js

@@ -10,12 +10,14 @@
 //   * honest: no solver reports `unsupported`, a deadline reports `timeout`, a malformed or failing solver
 //     reports `unknown`. None of these ever drops or downgrades the finding. The abstract result is kept.
 //
-// No solver ships here and no dependency is added. `noSolver` is the default stub. A real solver is an
+// `noSolver` is the default stub. The real backend is smt-z3-backend.js (optional `z3-solver`, lazy, used only
+// when a solver is passed in or AGENTIC_SECURITY_LINEAGE_SMT=z3 is set). A solver is an
 // object with `{ name, version?, available?, check(problem, { signal }) -> Promise<{ result }> }` where
 // `result` is 'sat' | 'unsat' | 'unknown'. `problem` is the solver-neutral view from `toSolverProblem`.
 // Satisfiability never implies exploitability.
 
 import { evaluateWitnessConditions, toSolverProblem, PATH_PREDICATE_VERSION, SATISFIABILITY_NOTE } from './path-predicates.js';
+import { sharedZ3Solver, smtBackendEnabled } from './smt-z3-backend.js';
 
 export const SOLVER_DEFAULT_TIMEOUT_MS = 1000;
 export const SOLVER_TIMEOUT_MAX_MS = 60_000;
@@ -26,7 +28,17 @@ export const noSolver = Object.freeze({
   async check() { return { result: 'unsupported' }; },
 });
 
-const MAP = Object.freeze({ sat: 'feasible-model', unsat: 'infeasible-under-model', unknown: 'unknown' });
+const MAP = Object.freeze({ sat: 'feasible-model', unsat: 'infeasible-under-model', unknown: 'unknown', timeout: 'timeout' });
+
+/**
+ * The solver a call uses. An explicit `solver` always wins. Otherwise the real z3 backend is used only when
+ * AGENTIC_SECURITY_LINEAGE_SMT=z3 is set (it loads lazily and reports `unsupported` if the optional package
+ * is missing); with nothing set the default is `noSolver`, so a default run never loads a solver.
+ */
+export function resolveSolver(solver, env = process.env) {
+  if (solver !== undefined) return solver;
+  return smtBackendEnabled(env) ? sharedZ3Solver() : noSolver;
+}
 
 /** Render the problem as SMT-LIB 2 text for a solver adapter that wants text. Opaque predicates become comments. */
 export function toSmtLib(problem) {
@@ -65,7 +77,8 @@ function boundedTimeout(ms) {
  *
  * @returns {Promise<{status:string, reasons:string[], solver:object, elapsedMs:number, semanticsVersion:string, limitations:string[]}>}
  */
-export async function checkWithSolver(collected, { solver = noSolver, timeoutMs, signal, now = Date.now } = {}) {
+export async function checkWithSolver(collected, { solver: solverOpt, timeoutMs, signal, now = Date.now } = {}) {
+  const solver = resolveSolver(solverOpt);
   const started = now();
   const info = { name: solver?.name ?? 'unknown', version: solver?.version ?? null };
   const out = (status, reasons, extra = {}) => ({
@@ -101,9 +114,10 @@ export async function checkWithSolver(collected, { solver = noSolver, timeoutMs,
     if (r && r.__timeout) { ac.abort(); return out('timeout', ['solver-deadline']); }
     if (r && r.__cancelled) { ac.abort(); return out('unknown', ['cancelled']); }
     const status = isObjectWithResult(r) ? MAP[r.result] : undefined;
-    if (r?.result === 'unsupported') return out('unsupported', ['solver-declined']);
+    if (r?.result === 'unsupported') return out('unsupported', ['solver-declined', ...(typeof r.reason === 'string' ? [r.reason] : [])]);
     if (!status) return out('unknown', ['solver-malformed']);
-    return out(status, [`solver-${r.result}`], r.result === 'sat' && r.model && typeof r.model === 'object' ? { model: r.model } : {});
+    const why = typeof r.reason === 'string' ? [r.reason] : [];
+    return out(status, [`solver-${r.result}`, ...why], r.result === 'sat' && r.model && typeof r.model === 'object' ? { model: r.model } : {});
   } catch {
     return out('unknown', ['solver-error']);
   } finally {
@@ -121,18 +135,40 @@ function isObjectWithResult(r) { return typeof r === 'object' && r !== null && t
  */
 export async function evaluateWitnessConditionsAsync(collected, o = {}) {
   const abstract = evaluateWitnessConditions(collected, o);
-  if (abstract.status !== 'unknown') return { ...abstract, abstractStatus: abstract.status, solverConsulted: false };
+  const consultFeasible = o.consultOnFeasible ?? smtBackendEnabled();
+  const refine = abstract.status === 'feasible-model' && consultFeasible && abstract.clauseRefs.length > 0;
+  if (abstract.status !== 'unknown' && !refine) return { ...abstract, abstractStatus: abstract.status, solverConsulted: false };
   const s = await checkWithSolver(collected, o);
-  if (s.status === 'unsupported') return { ...abstract, abstractStatus: abstract.status, solverConsulted: false, solver: s.solver, solverStatus: 'unsupported' };
+  const kept = { ...abstract, abstractStatus: abstract.status };
+  // Branch arms of one branch inside a loop may belong to different iterations. The solver's problem carries no
+  // iteration structure, so its `unsat` there is not evidence of infeasibility: the answer stays `unknown`.
+  const loopArms = abstract.reasons.includes('branch-arms-in-loop');
+  if (refine) {
+    // On a feasible-model answer ONLY a solver unsat changes anything; every other outcome keeps the abstract result.
+    if (s.status === 'infeasible-under-model' && !loopArms) return unsatResult(abstract, s);
+    return { ...kept, solverConsulted: s.status !== 'unsupported', solver: s.solver, solverStatus: s.status, elapsedMs: s.elapsedMs };
+  }
+  if (s.status === 'unsupported') return { ...kept, solverConsulted: false, solver: s.solver, solverStatus: 'unsupported' };
   if (s.status === 'timeout') {
-    return { ...abstract, status: 'timeout', reasons: [...abstract.reasons, 'solver-deadline'], abstractStatus: abstract.status, solverConsulted: true, solver: s.solver, solverStatus: 'timeout', elapsedMs: s.elapsedMs };
+    return { ...kept, status: 'timeout', reasons: [...abstract.reasons, 'solver-deadline'], solverConsulted: true, solver: s.solver, solverStatus: 'timeout', elapsedMs: s.elapsedMs };
+  }
+  if (s.status === 'infeasible-under-model' && loopArms) {
+    return { ...kept, solverConsulted: true, solver: s.solver, solverStatus: 'unknown', reasons: [...abstract.reasons, 'solver-unsat-not-trusted-in-loop'], elapsedMs: s.elapsedMs };
   }
   if (s.status === 'unknown') {
-    return { ...abstract, abstractStatus: abstract.status, solverConsulted: true, solver: s.solver, solverStatus: 'unknown', reasons: [...abstract.reasons, ...s.reasons], elapsedMs: s.elapsedMs };
+    return { ...kept, solverConsulted: true, solver: s.solver, solverStatus: 'unknown', reasons: [...abstract.reasons, ...s.reasons], elapsedMs: s.elapsedMs };
   }
+  if (s.status === 'infeasible-under-model') return unsatResult(abstract, s);
+  return {
+    ...kept, status: s.status, reasons: s.reasons, solverConsulted: true, solver: s.solver, solverStatus: s.status,
+    limitations: [...abstract.limitations, ...s.limitations], elapsedMs: s.elapsedMs, contradiction: null,
+  };
+}
+
+function unsatResult(abstract, s) {
   return {
-    ...abstract, status: s.status, reasons: s.reasons, abstractStatus: abstract.status, solverConsulted: true, solver: s.solver, solverStatus: s.status,
+    ...abstract, status: 'infeasible-under-model', reasons: s.reasons, abstractStatus: abstract.status, solverConsulted: true, solver: s.solver, solverStatus: s.status,
     limitations: [...abstract.limitations, ...s.limitations], elapsedMs: s.elapsedMs,
-    contradiction: s.status === 'infeasible-under-model' ? { kind: 'solver-unsat', refs: abstract.clauseRefs } : null,
+    contradiction: { kind: 'solver-unsat', refs: abstract.clauseRefs },
   };
 }