@boyingliu01/xp-gate 0.31.1 → 0.31.2

package/hooks/lib/toolchain-path.sh

@@ -0,0 +1,370 @@
+#!/bin/bash
+# Toolchain PATH bootstrap and tool resolution (#593).
+#
+# On Windows the hook runs under git-bash, which does NOT inherit the PATH entries
+# the caller added on the Windows side, and none of the standard install locations
+# for the toolchains these gates need are on git-bash's default PATH:
+#
+#   npm global CLIs      %APPDATA%\npm
+#   the node binary      C:\Program Files\nodejs
+#   pip --user scripts   %APPDATA%\Python\PythonNNN\Scripts
+#   hand-placed tools    ~/bin, ~/.local/bin
+#
+# Every gate that needs one of those probed only `command -v` / `npx --no-install`
+# / `~/.local/bin`, so "not on this shell's PATH" was reported as "not installed".
+# Four gates did that for tools that were installed, and two of the reports were
+# false GREENS (a gate that never ran, reported as a WARN that reads like an
+# optional tool missing).
+#
+# The fix belongs here, once, rather than in each gate: one bootstrap that appends
+# — never prepends — so the caller's PATH order stays authoritative.
+
+# Directories to append, one per line. Empty when nothing applies.
+#
+# Globbing the Python Scripts dirs instead of guessing a version is deliberate:
+# the version in the path is the interpreter's, not the tool's, and a repo may
+# have several.
+toolchain_path_candidates() {
+  local _home="${HOME:-}"
+  local _appdata="${APPDATA:-}"
+  local _node="${XP_GATE_NODE_DIR:-}"
+  local _d
+
+  # npm global CLIs. APPDATA is the Windows default; the unix-shaped locations are
+  # harmless on Linux/macOS because the loop below skips anything not a directory.
+  [ -n "$_appdata" ] && [ -d "$_appdata/npm" ] && printf '%s\n' "$_appdata/npm"
+  [ -n "$_home" ] && [ -d "$_home/.npm-global/bin" ] && printf '%s\n' "$_home/.npm-global/bin"
+
+  # The node install dir. Needed not only to run node CLIs but to run the npm POSIX
+  # shims, which exec `node` by name (#593 symptom 2).
+  if [ -n "$_node" ] && [ -d "$_node" ]; then
+    printf '%s\n' "$_node"
+  fi
+  if [ -n "$_appdata" ] && [ -d "$_appdata/npm/node_modules/.bin" ]; then
+    printf '%s\n' "$_appdata/npm/node_modules/.bin"
+  fi
+
+  # pip --user Scripts dirs, one per Python version found.
+  if [ -n "$_appdata" ] && [ -d "$_appdata/Python" ]; then
+    for _d in "$_appdata"/Python/Python*/Scripts; do
+      [ -d "$_d" ] && printf '%s\n' "$_d"
+    done
+  fi
+  # Unix-side pip --user and hand-placed tools.
+  [ -n "$_home" ] && [ -d "$_home/.local/bin" ] && printf '%s\n' "$_home/.local/bin"
+  [ -n "$_home" ] && [ -d "$_home/bin" ] && printf '%s\n' "$_home/bin"
+
+  return 0
+}
+
+# Append the toolchain locations to PATH. Idempotent: a second call is a no-op.
+#
+# APPENDS rather than prepends. A project that pins its own tool version must keep
+# winning; putting a global CLI in front would silently override it.
+bootstrap_toolchain_path() {
+  local _dir _added=0
+  while IFS= read -r _dir; do
+    [ -n "$_dir" ] || continue
+    case ":${PATH}:" in
+      *":${_dir}:"*) continue ;;
+    esac
+    PATH="${PATH}:${_dir}"
+    _added=$((_added + 1))
+  done <<EOF_TOOLCHAIN
+$(toolchain_path_candidates)
+EOF_TOOLCHAIN
+
+  # #596 point 2: the authoritative source is the ORIGINAL Windows PATH, not a list
+  # of guessed standard locations. A hook shell can run with a shrunken PATH while
+  # ORIGINAL_PATH still carries everything, and a custom prefix (D:\npm) shows up
+  # only there. Appended after the standard candidates, so an explicitly pinned
+  # project toolchain still wins.
+  while IFS= read -r _dir; do
+    [ -n "$_dir" ] || continue
+    case ":${PATH}:" in
+      *":${_dir}:"*) continue ;;
+    esac
+    [ -d "$_dir" ] || continue
+    PATH="${PATH}:${_dir}"
+    _added=$((_added + 1))
+  done <<EOF_ORIGINAL
+$(original_path_dirs)
+EOF_ORIGINAL
+
+  export PATH
+  _XP_GATE_TOOLCHAIN_BOOTSTRAPPED=1
+  return 0
+}
+
+# Environment variable that names a tool binary directly, in priority order.
+#
+# #580's first suggestion: a user whose toolchain lives somewhere unusual has no
+# way to say so today, and "put it on PATH" is not available to everyone — WSL with
+# appendWindowsPath=false has no Windows PATH at all.
+tool_env_override() {
+  case "$1" in
+    node) printf '%s\n' "${XP_GATE_NODE_BIN:-}" ;;
+    npx) printf '%s\n' "${XP_GATE_NPX_BIN:-}" ;;
+    npm) printf '%s\n' "${XP_GATE_NPM_BIN:-}" ;;
+    *) printf '%s\n' "" ;;
+  esac
+}
+
+# Is a tool available, counting the Windows `.exe` suffix and an env override?
+#
+# `command -v node` returns 1 on WSL and in git-bash even when
+# /mnt/c/Program Files/nodejs/node.exe exists and runs, because bash does not
+# append a suffix the way Windows does (#580). That single fact gave one gate a
+# silent SKIP and another a false BLOCK on the same machine:
+#
+#   Gate 1  "SKIP - npx not available"           fail-OPEN, reads like "nothing
+#                                                to check here"
+#   Gate 1  "BLOCKED - Biome check failed"       fail-CLOSED, wrong cause
+#   Gate 8  "BLOCKED - gitleaks not installed"   a security gate blocked by its
+#                                                own environment
+#
+# Both described an environment problem as a code problem.
+#
+# #596 adds the third and costliest variant: PRESENCE IS NOT EXECUTABILITY.
+# `command -v checkov` succeeds on a POSIX shim whose shebang execs `python`, on a
+# shell where `python` is not resolvable. The file is there, it is executable, and
+# running it dies at the `exec` with 127. Gate 7 counted zero usable scanners and
+# BLOCKED a commit under "no scanning tools available" — on a repo where checkov
+# 3.3.30 worked. So the probe now proves it can run.
+tool_is_available() {
+  local _tool="$1" _override _hit
+  _override=$(tool_env_override "$_tool")
+  if [ -n "$_override" ] && [ -x "$_override" ]; then
+    tool_can_execute "$_override"
+    return $?
+  fi
+
+  _hit=$(command -v "$_tool" 2>/dev/null || true)
+  if [ -z "$_hit" ]; then
+    # Harmless on Linux/macOS: no such file exists there.
+    _hit=$(command -v "${_tool}.exe" 2>/dev/null || true)
+  fi
+  if [ -z "$_hit" ]; then
+    # #596: a tool reachable only through the un-shrunk PATH still counts. Callers
+    # may probe before bootstrapping, so this cannot rely on the bootstrap having
+    # run.
+    _hit=$(find_tool_in_original_path "$_tool")
+  fi
+  [ -n "$_hit" ] || return 1
+
+  # Found — now prove it is not a shim pointing at an unreachable interpreter.
+  # A tool that exists but cannot run is NOT available; the caller reports it as a
+  # toolchain failure, which is a different and true statement from "not installed".
+  tool_can_execute "$_hit"
+}
+
+# The path of a tool found in ORIGINAL_PATH, or the empty string.
+#
+# @param {string} tool tool name
+# @returns {string}
+find_tool_in_original_path() {
+  local _tool="$1" _dir
+  while IFS= read -r _dir; do
+    [ -n "$_dir" ] || continue
+    if [ -x "$_dir/$_tool" ]; then
+      printf '%s' "$_dir/$_tool"
+      return 0
+    fi
+    if [ -x "$_dir/${_tool}.exe" ]; then
+      printf '%s' "$_dir/${_tool}.exe"
+      return 0
+    fi
+  done <<EOF_ORIGINAL_TOOL
+$(original_path_dirs)
+EOF_ORIGINAL_TOOL
+  return 0
+}
+
+# Can this resolved tool be executed?
+#
+# Runs `<tool> --version` under a timeout. Exit 127 is the shell's own "interpreter
+# not found" and is the precise signal for the broken-shim case. Any other non-zero
+# exit still counts as executable: a tool that runs and rejects `--version` exists
+# and works, and calling it missing would be the same defect in the other direction.
+#
+# @param {string} path resolved tool path
+# @returns 0 when the tool can be executed
+tool_can_execute() {
+  local _path="$1" _status=0
+  [ -n "$_path" ] && [ -x "$_path" ] || return 1
+  if command -v timeout >/dev/null 2>&1; then
+    timeout 20 "$_path" --version >/dev/null 2>&1 || _status=$?
+  else
+    "$_path" --version >/dev/null 2>&1 || _status=$?
+  fi
+  [ "$_status" -ne 127 ]
+}
+
+# Directories listed in ORIGINAL_PATH, one per line.
+#
+# #596 point 2: inside a hook shell $PATH can be a handful of entries (measured: 7)
+# while ORIGINAL_PATH still carries the full Windows PATH (measured: 3002 chars), and
+# a tool installed to a custom prefix appears only in the latter. Guessing standard
+# install locations — all #593's bootstrap does — cannot find a custom prefix.
+#
+# Normally unset on Linux/macOS, which yields nothing and is correct: there is no
+# shrunken-PATH problem there.
+original_path_dirs() {
+  local _raw="${ORIGINAL_PATH:-}"
+  [ -n "$_raw" ] || return 0
+  printf '%s' "$_raw" | tr ':' '\n' | sed -n '/./p'
+}
+
+# Resolve a tool to an absolute path, or return 1.
+#
+# Priority order, matching #580's suggestion:
+#   1. XP_GATE_<TOOL>_BIN override
+#   2. command -v <tool>
+#   3. command -v <tool>.exe            (a Windows binary seen from a *NIX* shell)
+#   4. npx --no-install
+#   5. subproject node_modules/.bin
+#
+# Covers the shapes `command -v` cannot see:
+#   * the `.exe` suffix (#580)
+#   * subproject node_modules/.bin (monorepos: jscpd is a devDependency of ui/)
+#   * the standard Windows toolchain locations, via the bootstrap
+#
+# Echoes the path on success.
+resolve_tool_path() {
+  local _tool="$1" _hit _d _override
+  local _base="${PROJECT_ROOT:-$(pwd)}"
+
+  # #580: an explicit override wins over every probe.
+  _override=$(tool_env_override "$_tool")
+  if [ -n "$_override" ] && [ -x "$_override" ]; then
+    printf '%s\n' "$_override"
+    return 0
+  fi
+
+  _hit=$(command -v "$_tool" 2>/dev/null || true)
+  if [ -z "$_hit" ]; then
+    # #580: the .exe suffix. bash does not append it the way Windows does, so a
+    # bootstrapped Windows toolchain stays invisible without this second probe —
+    # and every gate keeps reporting an installed tool as missing.
+    _hit=$(command -v "${_tool}.exe" 2>/dev/null || true)
+  fi
+  if [ -n "$_hit" ]; then
+    printf '%s\n' "$_hit"
+    return 0
+  fi
+
+  # npx knows about the project's own node_modules.
+  if tool_is_available npx; then
+    if npx --no-install "$_tool" --version >/dev/null 2>&1; then
+      printf '%s\n' "$_tool"
+      return 0
+    fi
+  fi
+
+  # Subproject node_modules/.bin, shallow then one level deep. A monorepo's ui/ or
+  # server/ package is the normal case; deeper nesting is rare enough that a full
+  # find would cost more than it returns.
+  for _d in "$_base/node_modules/.bin/$_tool" "$_base"/*/node_modules/.bin/"$_tool"; do
+    if [ -x "$_d" ]; then
+      printf '%s\n' "$_d"
+      return 0
+    fi
+  done
+
+  return 1
+}
+
+# Put the directory of a resolved tool on PATH, so the tool's own siblings are
+# reachable, and print that directory.
+#
+# semgrep(.exe) is a zipapp wrapper that execs the sibling `pysemgrep`. Resolving
+# the wrapper is not enough: if its directory is not on PATH the wrapper dies with
+# `executing pysemgrep failed: No such file or directory`, which Gate 10 then
+# reported as "tool not installed" (#593 symptom 4).
+#
+# WARNING: call this directly, never as `$(resolve_tool_dir x)`. A command
+# substitution runs in a subshell, so the PATH change would be discarded and the
+# caller would get the directory name while the tool stayed broken — which is
+# exactly how this bit its own first test. Read the directory from
+# `$(resolve_tool_dir ...)` only if you do not need the PATH side effect; otherwise
+# call it and capture with a plain assignment from a file or use
+# `ensure_tool_dir_on_path`.
+resolve_tool_dir() {
+  local _tool="$1" _path _dir
+  bootstrap_toolchain_path
+  _path=$(resolve_tool_path "$_tool") || return 1
+  if [ -f "$_path" ]; then
+    _dir=$(cd "$(dirname "$_path")" && pwd)
+  else
+    _dir=$(pwd)
+  fi
+  case ":${PATH}:" in
+    *":${_dir}:"*) ;;
+    *) PATH="${_dir}:${PATH}"; export PATH ;;
+  esac
+  printf '%s\n' "$_dir"
+  return 0
+}
+
+# Side-effect-only variant: put the tool's directory on PATH in the CALLER's
+# shell. Returns 0 on success, 1 when the tool cannot be resolved.
+#
+# This is the one to call from a gate that is about to run the tool.
+ensure_tool_dir_on_path() {
+  local _tool="$1" _dir
+  bootstrap_toolchain_path
+  _dir=$(resolve_tool_path "$_tool") || return 1
+  if [ -f "$_dir" ]; then
+    _dir=$(cd "$(dirname "$_dir")" && pwd)
+  else
+    _dir=$(pwd)
+  fi
+  case ":${PATH}:" in
+    *":${_dir}:"*) ;;
+    *) PATH="${_dir}:${PATH}"; export PATH ;;
+  esac
+  return 0
+}
+
+# Human-readable list of everywhere a tool is looked for, for the "not available"
+# message.
+#
+# "not installed" and "installed but not found" need different fixes, and the old
+# message could only say the first (#593 point 3).
+describe_tool_search() {
+  local _tool="$1" _base="${PROJECT_ROOT:-$(pwd)}"
+  printf '   Searched: PATH entries'
+  printf ', %s' "$_base/node_modules/.bin/$_tool" "$_base"/*/node_modules/.bin/"$_tool"
+  local _extra
+  _extra=$(toolchain_path_candidates | tr '\n' ',' | sed 's/,$//')
+  if [ -n "$_extra" ]; then
+    printf ', toolchain dirs (%s)' "$_extra"
+  fi
+  printf '\n'
+  printf '   If the tool IS installed, this is a PATH problem, not a missing install.\n'
+}
+
+# Classify a non-zero exit from a tool: TOOLCHAIN or FINDING.
+#
+#   $1 -- the tool's exit status
+#   $2 -- everything it printed
+#
+# Exit 127 plus an exec/"not found" line means the shim resolved but its
+# interpreter did not. Gate 6 printed
+#     ❌ BLOCKED - Architecture violations detected
+# for exactly that, pointing the reader at code that was fine (#593 symptom 2).
+#
+# The FINDING default matters as much: if everything looked like a toolchain
+# problem, no gate could ever block on a real violation.
+classify_tool_failure() {
+  local _exit="$1" _out="$2"
+  if [ "$_exit" -eq 127 ] 2>/dev/null; then
+    printf 'TOOLCHAIN\n'
+    return 0
+  fi
+  if printf '%s' "$_out" | grep -qiE 'exec: [^ ]+: not found|command not found|No such file or directory.*exec|pysemgrep failed'; then
+    printf 'TOOLCHAIN\n'
+    return 0
+  fi
+  printf 'FINDING\n'
+}

package/hooks/lib/validate-code-walkthrough.cjs

@@ -2,10 +2,21 @@
 'use strict';
 
 const fs = require('node:fs');
+const path = require('node:path');
 
 const REQUIRED_ROLES = ['architecture', 'technical', 'feasibility'];
 const VALIDITY_MS = 60 * 60 * 1000;
 
+/**
+ * Project-level Delphi seat configuration.
+ *
+ * Present => evidence is BOUND to it (#574): each expert's `requested_model`
+ * must be exactly the seat the config assigns to that expert's role.
+ * Absent  => evidence stays unbound (the #423 behaviour), so projects that
+ * review through another platform's channel are unaffected.
+ */
+const DELPHI_CONFIG_FILE = '.delphi-config.json';
+
 /**
  * Allowed provenance values for an expert record.
  *
@@ -58,7 +69,126 @@ function parseTimestamp(value, field) {
   return date.getTime();
 }
 
-function validateExpert(expert, index, roles, models, resolvedModels) {
+/**
+ * Record one seat into `seats` if the entry carries a usable model id.
+ * Shared by both `experts` shapes so the acceptance rule lives in exactly one
+ * place (#599: the two branches were byte-for-byte copies, which is what pushed
+ * this function over the complexity block threshold).
+ *
+ * @param {Map<string, string>} seats role -> trimmed model id, mutated
+ * @param {string} role configured role name
+ * @param {unknown} entry candidate expert record
+ */
+function addSeat(seats, role, entry) {
+  if (!isPlainObject(entry)) return;
+  const model = entry.model ?? entry.requested_model;
+  if (typeof model === 'string' && model.trim() !== '') seats.set(role, model.trim());
+}
+
+/**
+ * Normalise the two `experts` shapes `.delphi-config.json` appears in — an
+ * object keyed by role (what xp-gate writes) and an array carrying `role` —
+ * into a plain role -> model map. Mirrors `normalizeExperts()` in
+ * `plugins/dsh/src/delphi-config.ts` and `iter_seats()` in
+ * `scripts/check_delphi_local_models.py`: one config shape, one reading.
+ *
+ * @param {unknown} experts raw `experts` value
+ * @returns {Map<string, string>} role -> trimmed model id
+ */
+function seatsFromExperts(experts) {
+  const seats = new Map();
+  if (Array.isArray(experts)) {
+    for (const entry of experts) {
+      if (isPlainObject(entry) && typeof entry.role === 'string') {
+        addSeat(seats, entry.role, entry);
+      }
+    }
+  } else if (isPlainObject(experts)) {
+    for (const [role, entry] of Object.entries(experts)) {
+      addSeat(seats, role, entry);
+    }
+  }
+  return seats;
+}
+
+/**
+ * Resolve the binding seats from a parsed `.delphi-config.json`.
+ *
+ * Only the ACTIVE profile binds, exactly like every other Delphi loader. A
+ * config that names profiles but leaves no resolvable active one is rejected
+ * rather than ignored: silently falling back to "unbound" would turn a broken
+ * config into a bypass.
+ *
+ * @param {unknown} config parsed config document
+ * @returns {Map<string, string>} role -> model id that evidence must match
+ */
+function resolveBindingSeats(config) {
+  if (!isPlainObject(config)) fail(`${DELPHI_CONFIG_FILE} must contain a JSON object.`);
+
+  const profiles = config.profiles;
+  if (!isPlainObject(profiles) || Object.keys(profiles).length === 0) {
+    // Legacy/flat shape: experts live at the top level.
+    return seatsFromExperts(config.experts);
+  }
+
+  const active = config.active_profile;
+  if (typeof active !== 'string' || !isPlainObject(profiles[active])) {
+    const available = Object.keys(profiles).join(', ');
+    fail(
+      `${DELPHI_CONFIG_FILE} has no resolvable active_profile (active_profile=${JSON.stringify(active)}; `
+        + `available: ${available}). Set one so the gate knows which seats bind.`
+    );
+  }
+  return seatsFromExperts(profiles[active].experts);
+}
+
+/**
+ * Read the binding seats for the project rooted at `projectRoot`.
+ *
+ * The root is passed EXPLICITLY by the caller, never derived from
+ * `process.cwd()`. Deriving it from cwd made the binding depend on where the
+ * validator was launched from: running the test suite from inside xp-gate
+ * itself picked up xp-gate's own `.delphi-config.json` and re-bound every
+ * fixture to xp-gate's seats. The gate's subject is the repository being
+ * pushed, so that is what must be named.
+ *
+ * @param {string} projectRoot repository root whose config binds the evidence
+ * @returns {Map<string, string> | null} seats, or null when no config exists
+ */
+function loadBindingSeats(projectRoot) {
+  const configPath = path.join(projectRoot, DELPHI_CONFIG_FILE);
+  let raw;
+  try {
+    raw = fs.readFileSync(configPath, 'utf8');
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return null;
+    fail(`cannot read ${DELPHI_CONFIG_FILE}: ${error && error.message ? error.message : String(error)}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    fail(`${DELPHI_CONFIG_FILE} is not valid JSON: ${error.message}`);
+  }
+  const seats = resolveBindingSeats(parsed);
+  for (const role of REQUIRED_ROLES) {
+    if (!seats.has(role)) {
+      fail(`${DELPHI_CONFIG_FILE} declares no seat for the ${role} role; all three roles must be configured.`);
+    }
+  }
+  return seats;
+}
+
+/**
+ * Validate an expert's identity fields: shape, role, approval status, and
+ * channel provenance. Split out of `validateExpert`, which exceeded the
+ * complexity block threshold (#599).
+ *
+ * @param {object} expert expert record
+ * @param {number} index position in the experts array
+ * @param {Set<string>} roles roles seen so far; the role is added
+ */
+function validateExpertIdentity(expert, index, roles) {
   if (!isPlainObject(expert)) fail(`experts[${index}] must be a plain object.`);
   if (!REQUIRED_ROLES.includes(expert.role)) fail(`experts[${index}].role is invalid.`);
   if (roles.has(expert.role)) fail(`expert role ${expert.role} is duplicated.`);
@@ -80,14 +210,33 @@ function validateExpert(expert, index, roles, models, resolvedModels) {
       `expert ${expert.role} channel must be one of: ${VALID_CHANNELS.join(', ')}.`
     );
   }
+}
 
-  // requested_model is compared EXACTLY (after trimming); resolved_model below is
-  // compared case-INSENSITIVELY. The asymmetry is intentional, not an oversight:
-  // a requested ID is a case-sensitive gateway identifier and AGENTS.md requires
-  // "three distinct trimmed requested model IDs", whereas resolved_model answers
-  // "did these actually run on one model?" -- and gateways do report the same model
-  // with different casing per call, which is how #423 slipped through. Pinned by
-  // scripts/__tests__/gate-mw-provenance.test.cjs (AC-423-08).
+/**
+ * Validate the requested model: non-empty, distinct across experts, and — when
+ * the project binds seats — exactly the model configured for this role.
+ *
+ * requested_model is compared EXACTLY (after trimming) while resolved_model is
+ * compared case-INSENSITIVELY. The asymmetry is intentional, not an oversight: a
+ * requested ID is a case-sensitive gateway identifier and AGENTS.md requires
+ * "three distinct trimmed requested model IDs", whereas resolved_model answers
+ * "did these actually run on one model?" -- and gateways do report the same model
+ * with different casing per call, which is how #423 slipped through. Pinned by
+ * scripts/__tests__/gate-mw-provenance.test.cjs (AC-423-08).
+ *
+ * #574: when the project ships a `.delphi-config.json`, the seat this role was
+ * configured with is the ONLY model allowed to report for it. Distinctness alone
+ * was satisfiable by any three of the gateway's ~138 models -- measured
+ * 2026-10-22, a walkthrough ran on s-deepseek-v4.1-flash / g-deepseek-v4-pro /
+ * doubao-seed-2.0-pro while the config named three local-* seats, and this
+ * validator passed it. Membership is checked per ROLE (not as a set) so a swapped
+ * pair is rejected too: the role attribution would otherwise be a lie.
+ *
+ * @param {object} expert expert record
+ * @param {Set<string>} models requested models seen so far; this one is added
+ * @param {Map<string, string>|null} bindingSeats configured seats, or null
+ */
+function validateRequestedModel(expert, models, bindingSeats) {
   if (typeof expert.requested_model !== 'string' || expert.requested_model.trim() === '') {
     fail(`expert ${expert.role} requested_model must be non-empty.`);
   }
@@ -95,10 +244,28 @@ function validateExpert(expert, index, roles, models, resolvedModels) {
   if (models.has(model)) fail(`requested_model ${model} is duplicated.`);
   models.add(model);
 
-  // `resolved_model` must be a real, DISTINCT model. Previously null was allowed,
-  // so an expert that never resolved a model still counted as successful; and
-  // nothing compared resolved models, so all three could report the same one
-  // while `requested_model` differed.
+  if (bindingSeats !== null) {
+    const configured = bindingSeats.get(expert.role);
+    if (model !== configured) {
+      fail(
+        `expert ${expert.role} requested_model ${model} does not match the configured seat `
+          + `${configured} from ${DELPHI_CONFIG_FILE}.`
+      );
+    }
+  }
+}
+
+/**
+ * Validate the resolved model: a non-empty string, distinct ignoring case.
+ *
+ * Previously null was allowed, so an expert that never resolved a model still
+ * counted as successful; and nothing compared resolved models, so all three could
+ * report the same one while `requested_model` differed.
+ *
+ * @param {object} expert expert record
+ * @param {Set<string>} resolvedModels resolved models seen so far; added here
+ */
+function validateResolvedModel(expert, resolvedModels) {
   if (typeof expert.resolved_model !== 'string' || expert.resolved_model.trim() === '') {
     fail(`expert ${expert.role} resolved_model must be a non-empty string.`);
   }
@@ -109,7 +276,13 @@ function validateExpert(expert, index, roles, models, resolvedModels) {
   resolvedModels.add(resolved);
 }
 
-function validateEvidence(evidence, expectedCommit, expectedBranch, now) {
+function validateExpert(expert, index, roles, models, resolvedModels, bindingSeats) {
+  validateExpertIdentity(expert, index, roles);
+  validateRequestedModel(expert, models, bindingSeats);
+  validateResolvedModel(expert, resolvedModels);
+}
+
+function validateEvidence(evidence, expectedCommit, expectedBranch, now, bindingSeats) {
   if (!isPlainObject(evidence)) fail('top level must be a plain object.');
   if (evidence.commit !== expectedCommit) fail('commit does not match HEAD.');
   if (evidence.branch !== expectedBranch) fail('branch does not match the current branch.');
@@ -139,25 +312,53 @@ function validateEvidence(evidence, expectedCommit, expectedBranch, now) {
   // next (a long-lived process validating several pushes).
   const resolvedModels = new Set();
   evidence.experts.forEach((expert, index) => {
-    validateExpert(expert, index, roles, models, resolvedModels);
+    validateExpert(expert, index, roles, models, resolvedModels, bindingSeats);
   });
   if (roles.size !== REQUIRED_ROLES.length) fail('all required expert roles must be present.');
 }
 
+/**
+ * Read and parse the evidence document, failing with a readable message rather
+ * than letting a raw ENOENT/JSON.parse error escape.
+ *
+ * @param {string} file path to the evidence JSON
+ * @returns {unknown} parsed document
+ */
+function readEvidence(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return fail('file must exist and contain valid JSON.');
+  }
+}
+
+/**
+ * Resolve the project root the caller named, if any.
+ *
+ * #574: the seats that bind are the ones configured in the repository being
+ * pushed. The caller names that root; a missing argument means "no project
+ * context", which keeps evidence unbound rather than guessing from cwd.
+ *
+ * @param {string|undefined} projectRoot raw argv value
+ * @returns {string|null} absolute root, or null for "no project context"
+ */
+function resolveProjectRoot(projectRoot) {
+  if (projectRoot === undefined || projectRoot === '') return null;
+  return path.resolve(projectRoot);
+}
+
 function main() {
-  const [file, expectedCommit, expectedBranch, nowValue] = process.argv.slice(2);
+  const [file, expectedCommit, expectedBranch, nowValue, projectRoot] = process.argv.slice(2);
   if (!file || !expectedCommit || !expectedBranch) {
-    fail('usage: validate-code-walkthrough.cjs <file> <commit> <branch> [now].');
+    fail(`usage: validate-code-walkthrough.cjs <file> <commit> <branch> [now] [project-root].`);
   }
 
-  let evidence;
-  try {
-    evidence = JSON.parse(fs.readFileSync(file, 'utf8'));
-  } catch {
-    fail('file must exist and contain valid JSON.');
-  }
+  const evidence = readEvidence(file);
   const now = nowValue === undefined ? Date.now() : parseTimestamp(nowValue, 'current time');
-  validateEvidence(evidence, expectedCommit, expectedBranch, now);
+
+  const root = resolveProjectRoot(projectRoot);
+  const bindingSeats = root === null ? null : loadBindingSeats(root);
+  validateEvidence(evidence, expectedCommit, expectedBranch, now, bindingSeats);
 }
 
 main();