[Change] comments: T3 inline prose rehousing + files/maldet audit

[Change] Rehouse long inline prose comments above their code lines (move, not delete) where context justifies
[Change] files/maldet audit-only pass: 1 trim applied within R10 10-line cap
[Change] NO-TOUCH verified: HTML/CSS in lmd_alert.sh, format specs in lmd_quarantine.sh, suppression justifications in lmd_sigs.sh
[Change] Restatement sweep: trim Arg/Usage/Input/Output parameter docs, stage catalogues, action-verb labels across 18 files
[Change] Cumulative: 28 files, -152 comment-only lines across T1+T2+T3, primitive compliance achieved (12.0%)
[Change] Applies parent CLAUDE.md Code Comments primitive (inline comments explain why not what)

Author: rfxn

CHANGELOG

@@ -75,6 +75,7 @@ v2.0.1 | Mar 25 2026:
 
   -- Changes --
 
+[Change] comments: T3 inline prose rehousing + restatement sweep across 18 files
 [Change] comments: T2 function-header normalization — collapse signature-restatement blocks
 [Change] comments: T1 mechanical cleanup — strip banner separators and file-header catalogues
 [Change]   - Delete 20 pure-dash banners (lmd_hook.sh: 14, lmd_alert.sh: 6)

CHANGELOG.RELEASE

@@ -75,6 +75,7 @@ v2.0.1 | Mar 25 2026:
 
   -- Changes --
 
+[Change] comments: T3 inline prose rehousing + restatement sweep across 18 files
 [Change] comments: T2 function-header normalization — collapse signature-restatement blocks
 [Change] comments: T1 mechanical cleanup — strip banner separators and file-header catalogues
 [Change]   - Delete 20 pure-dash banners (lmd_hook.sh: 14, lmd_alert.sh: 6)

cron.daily

@@ -77,15 +77,13 @@ if [ "$autoupdate_version" == "1" ] || [ "$autoupdate_signatures" == "1" ]; then
 fi
 
 if [ "$autoupdate_version" == "1" ]; then
-	# check for new release version
 	$inspath/maldet -d 1 2>&1 | tail -20 >> "$maldet_log"
 	if [ "${PIPESTATUS[0]}" -ne 0 ]; then
 		echo "$(date) cron.daily: maldet -d (version update) failed" >> "$maldet_log"
 	fi
 fi
 
 if [ "$autoupdate_signatures" == "1" ]; then
-	# check for new definition set
 	$inspath/maldet -u 1 2>&1 | tail -20 >> "$maldet_log"
 	if [ "${PIPESTATUS[0]}" -ne 0 ]; then
 		echo "$(date) cron.daily: maldet -u (signature update) failed" >> "$maldet_log"

files/hookscan.sh

@@ -127,8 +127,6 @@ _hook_rate_check() {
 }
 
 # Mode dispatch
-# Determine mode and file from arguments.
-# [[ "$1" == /* ]] distinguishes mode keyword from file path.
 # No mode arg AND path as $1 = backward compat modsec mode.
 # Pure-ftpd auto-detect: if UPLOAD_VUSER env var set, default to ftp mode.
 
@@ -248,7 +246,6 @@ if [ -z "$_list_mode" ]; then
 	fi
 fi
 
-# Source internals.conf for binary paths
 inspath="${inspath:-/usr/local/maldetect}"
 intcnf="$inspath/internals/internals.conf"
 if [ -f "$intcnf" ]; then
@@ -257,8 +254,6 @@ if [ -f "$intcnf" ]; then
 fi
 
 # Config parser (inline allowlist)
-# Read conf.maldet.hookscan if it exists. Only whitelisted variable names
-# are accepted. Shell metacharacters in values are rejected.
 
 hookcnf="$inspath/conf.maldet.hookscan"
 if [ -f "$hookcnf" ]; then
@@ -284,7 +279,6 @@ if [ -f "$hookcnf" ]; then
 			continue
 		fi
 
-		# Allowlist of known config keys
 		case "$_key" in
 			quarantine_hits)        quarantine_hits="$_val" ;;
 			quarantine_clean)       quarantine_clean="$_val" ;;
@@ -323,8 +317,6 @@ if [ -f "${elog_lib:-}" ]; then
 fi
 
 # Caller identity resolution
-# Resolve UID, homedir, and service-user status once.
-# Used by both single-file homedir check and per-line list validation.
 
 _is_root=1
 _user_home=""
@@ -350,7 +342,6 @@ fi
 # Rate limit check (non-root generic mode only)
 _hook_rate_check
 
-# Single-file homedir restriction
 if [ -z "$_list_mode" ] && [ "$_is_root" == "0" ] && [ "$_is_service_user" == "0" ] && [ -n "$_user_home" ]; then
 	case "$file" in
 		"$_user_home"/*)
@@ -369,7 +360,6 @@ fi
 if [ -n "$_list_mode" ]; then
 	tmpdir="${tmpdir:-$inspath/tmp}"
 
-	# Stdin capture
 	if [ "$_list_mode" == "stdin" ]; then
 		# Reject interactive terminal input
 		if [ -t 0 ]; then
@@ -626,11 +616,6 @@ fi
 # maldet --hook-scan outputs:
 #   "0 maldet: SIG PATH"  for infections
 #   "1 maldet: OK"         for clean
-# The exit code from timeout:
-#   0   = scan completed clean
-#   2   = scan completed, malware found
-#   124 = timeout expired
-#   *   = other error
 
 case "$_scan_rc" in
 	0)

files/internals/lmd_alert.sh

@@ -81,7 +81,6 @@ _lmd_parse_hitlist() {
 		if (sig ~ /^\{[A-Z][A-Z0-9]*\\\}/) {
 			sub(/\\\}/, "}", sig)
 		}
-		# Extract hit type from {TYPE} prefix
 		hit_type = ""
 		if (match(sig, /^\{[A-Z][A-Z0-9]*\}/)) {
 			hit_type = substr(sig, 2, RLENGTH - 2)
@@ -576,11 +575,9 @@ _lmd_render_json_legacy() {
 	# Initialize metadata vars to empty (prevent stale leaks from prior calls)
 	scanid="" scan_start_hr="" scan_end_hr="" scan_et="" file_list_et=""
 	hrspath="" days="" tot_files="" tot_hits="" tot_cl="" _hostname=""
-	# Parse session header if available
 	if [ -n "$_sess_file" ] && [ -f "$_sess_file" ]; then
 		_parse_session_metadata "$_sess_file"
 	fi
-	# Parse hits into 6-field manifest if available
 	if [ -n "$_hits_file" ] && [ -f "$_hits_file" ] && [ -s "$_hits_file" ]; then
 		_lmd_parse_hitlist "$_hits_file" > "$_manifest"
 	fi
@@ -938,7 +935,6 @@ _lmd_render_messaging() {
 	export ENTRY_FIELDS_DISCORD="$_discord_fields"
 	export SUBJECT="$subject"
 
-	# Render and dispatch per channel
 	local rc=0
 
 	local _ch_err
@@ -1370,7 +1366,6 @@ _genalert_digest() {
 	tot_files=$($wc -l < "$tmpdir/.digest.monitor.alert")
 	tot_susp=$($wc -l < "$tmpdir/.digest.susp.hits")
 
-	# Count hook hits
 	local _hook_hit_count
 	_hook_hit_count=$($wc -l < "$tmpdir/.digest.hook.hits")
 
@@ -1478,7 +1473,6 @@ _genalert_digest() {
 _test_scan_hits() {
 	local _session
 	_session=$(mktemp "$tmpdir/.test_session.XXXXXX")
-	# Set scan metadata for session header
 	local _save_scanid="${scanid:-}"
 	local _save_hrspath="${hrspath:-}"
 	local _save_tot_files="${tot_files:-}"
@@ -1530,7 +1524,6 @@ _test_alert_scan() {
 	local _session
 	_session=$(_test_scan_hits)
 
-	# Set test prefix for subject
 	local _orig_subj="${email_subj:-}"
 	email_subj="[TEST] ${email_subj:-maldet alert}"
 
@@ -1607,7 +1600,6 @@ _test_alert_scan() {
 }
 
 # _test_alert_digest channel — dispatch a test digest alert to a single channel
-# Creates temporary hook.hits.log entries, invokes genalert digest, then cleans up.
 # Applies channel isolation (S-REG-004) and truncates test entries after dispatch (S-REG-002).
 _test_alert_digest() {
 	local _channel="$1"
@@ -1680,7 +1672,6 @@ _test_alert_digest() {
 	local _save_tot_hits="${tot_hits:-}" _save_tot_files="${tot_files:-}" _save_tot_cl="${tot_cl:-}"
 	local _save_scanid="${scanid:-}"
 
-	# Set test subject prefix
 	local _orig_subj="${email_subj:-}"
 	email_subj="[TEST] ${email_subj:-maldet alert}"
 

files/internals/lmd_config.sh

@@ -29,15 +29,12 @@ detect_control_panel() {
 		pex_script=$(readlink -e /usr/local/interworx/bin/listaccounts.pex)
 		siteworx=$(command -v siteworx)
 
-		# Check that Iworx services are running
 		if [[ -z "$iworx_db_ps" || -z "$iworx_web_ps" ]]; then
 			control_panel="error"
 			eout "{panel} Interworx found, but not running. Panel user alerts will not be sent."
-		# Verify pex script exists and is executable
 		elif ! [[ -x "$pex_script" ]]; then
 			control_panel="error"
 			eout "{panel} Interworx found, but scripts are missing or not executable. Panel user alerts will not be sent."
-		# Ensure /usr/bin/siteworx is executable
 		elif ! [[ -x "$siteworx" ]]; then
 			control_panel="error"
 			eout "{panel} Interworx found, but Siteworx CLI is missing or not executable. Panel user alerts will not be sent."
@@ -49,11 +46,9 @@ detect_control_panel() {
 		cpapi=$(command -v cpapi2)
 		apitool=$(readlink -e ${cpapi})
 
-		# Ensure cpanel service is running
 		if [[ -z ${cpanel_ps} ]]; then
 			control_panel="error"
 			eout "{panel} cPanel found, but services are not running. Panel user alerts will not be sent."
-		# Verify apitool is executable
 		elif ! [[ -x ${apitool} ]]; then
 			control_panel="error"
 			eout "{panel} cPanel found, but apitool is missing or not found. Panel user alerts will not be sent."
@@ -104,7 +99,6 @@ _grf_cleanup() {
 }
 
 get_remote_file() {
-	# $1 = URI, $2 = local service identifier, $3 boolean verbose
 	local get_uri="$1"
 	local service="$2"
 	local verbose="$3"
@@ -288,7 +282,6 @@ _safe_source_conf() {
 				\"*\") _ssc_val="${_ssc_val#\"}"; _ssc_val="${_ssc_val%\"}" ;;
 				\'*\') _ssc_val="${_ssc_val#\'}"; _ssc_val="${_ssc_val%\'}" ;;
 			esac
-			# Reject values containing shell metacharacters
 			case "$_ssc_val" in
 				*'$'*|*'`'*|*';'*|*'|'*|*'&'*|*'('*|*')'*)
 					eout "{importconf} WARNING: rejected unsafe line in remote config: $_ssc_var"
@@ -406,7 +399,8 @@ import_conf() {
 			fi
 		fi
 		if [ -f "$sessdir/.import_conf.cache" ]; then
-			if [ -z "$_lmd_cli_co_applied" ]; then # skip re-source when CLI -co overrides are active — re-sourcing would discard them
+			# skip re-source when CLI -co overrides are active — re-sourcing would discard them
+			if [ -z "$_lmd_cli_co_applied" ]; then
 				source "$intcnf"
 				source "$cnf"
 			fi

files/internals/lmd_engine.sh

@@ -20,12 +20,8 @@ _hash_batch_worker() {
 	# Self-contained batch hash scanner for a chunk of files.
 	# Runs in a subshell (backgrounded by caller).
 	# Outputs tab-delimited filepath\thash\tsigname triples to stdout.
-	# Arg 1: hash command (full path from internals.conf, e.g., $md5sum)
-	# Arg 2: temp file label ("md5" or "sha256") — must match _scan_cleanup() globs
-	# Arg 3: chunk file (one filepath per line)
-	# Arg 4: runtime sig file (HASH:SIZE:{TYPE}sig.name.N)
-	# Arg 5: progress file (written every 500 files; empty = no progress)
-	# Arg 6: scanid (for lifecycle sentinel checks; empty = no checks)
+	# _hash_label must match _scan_cleanup() globs
+	# _sigfile format: HASH:SIZE:{TYPE}sig.name.N
 	local _hashcmd="$1" _hash_label="$2" _chunk="$3" _sigfile="$4" _progress_file="${5:-}"
 	local _w_scanid="${6:-}"
 	local _hash_out
@@ -156,7 +152,6 @@ _hex_csig_batch_worker() {
 	local _w_scanid="${12:-}"
 	local _chunk_skip="${13:-0}"
 
-	# Derive worker ID from chunk filename suffix (e.g., .hex_chunk.PID.3 → wid=3)
 	local _wid="${_chunk##*.}"
 
 	# Chunk counter for checkpoint tracking and chunk-skip
@@ -306,7 +301,6 @@ _hex_csig_batch_worker() {
 	fi
 
 	# Phase 3: CSIG pattern matching (batch approach)
-	# Skip entirely if no compiled rules or scan_csig disabled
 	if [ -n "$_csig_batch_compiled" ] && [ -s "$_csig_batch_compiled" ]; then
 		local _match_dir
 		_match_dir=$(mktemp -d "$tmpdir/.csig_mtx.$$.XXXXXX")

files/internals/lmd_hook.sh

@@ -175,7 +175,6 @@ _scan_hook_build_env() {
 		fi
 	fi
 
-	# Export LMD_* variables into current process env for hook inheritance
 	export LMD_SCAN_TYPE="$_scan_type"
 	export LMD_SCANID="${scanid:-}"
 	export LMD_HITS="$_hits"
@@ -291,15 +290,13 @@ _scan_hook_exec_sync() {
 	local _scan_type="$3"
 	local _json_stdin="$4"
 
-	# Discover timeout command at dispatch time
 	local _timeout_cmd
 	_timeout_cmd=$(command -v timeout 2>/dev/null) || _timeout_cmd="" # may be absent on minimal installs
 
 	if [ -z "$_timeout_cmd" ] && [ "$_timeout" -gt 0 ]; then
 		eout "{hook} WARNING: 'timeout' command not found; hook will run without timeout protection"
 	fi
 
-	# Build positional arguments: $1=SCANID $2=HITS $3=FILES $4=EXIT_CODE $5=SCAN_TYPE $6=PATH
 	local _hook_hits="${tot_hits:-0}"
 	case "$_scan_type" in
 		digest)
@@ -326,7 +323,6 @@ _scan_hook_exec_sync() {
 		"${hrspath:-}"
 	)
 
-	# Set LMD_* env and clear sensitive vars before executing
 	_scan_hook_build_env "$_scan_type"
 
 	# Capture stderr for diagnostics on non-zero exit
@@ -367,7 +363,6 @@ _scan_hook_exec_sync() {
 		fi
 	fi
 
-	# Log result and fire elog event
 	if [ "$_hook_rc" -eq 124 ]; then
 		eout "{hook} post-scan hook timeout after ${_timeout}s: $_hook_path"
 		_lmd_elog_event "${ELOG_EVT_HOOK_TIMEOUT:-hook_timeout}" "warning" \
@@ -385,7 +380,6 @@ _scan_hook_exec_sync() {
 			"hook completed" "hook=$_hook_path" "rc=$_hook_rc"
 	fi
 
-	# Clean up temp stderr file
 	[ -f "${_stderr_tmp:-}" ] && command rm -f "$_stderr_tmp" # temp cleanup; ignore error if already removed
 
 	return "$_hook_rc"
@@ -477,7 +471,6 @@ _scan_hook_exec_async() {
 		# Replace subshell fds: prevents inherited pipe fds from blocking the parent
 		exec >/dev/null 2>&1
 
-		# Export all LMD_* env vars using snapshotted values
 		export LMD_SCAN_TYPE="$_scan_type"
 		export LMD_SCANID="$_snap_scanid"
 		export LMD_HITS="$_snap_hits"
@@ -495,7 +488,6 @@ _scan_hook_exec_async() {
 		export LMD_MONITOR_UPTIME="0"
 		export LMD_HOOK_HITS="$_snap_hits"
 
-		# Clear sensitive credential variables
 		unset slack_token smtp_pass smtp_user telegram_bot_token
 		unset discord_webhook_url elk_host ALERT_SMTP_PASS ALERT_SMTP_USER
 
@@ -568,20 +560,17 @@ _scan_hook_dispatch() {
 		_exec="async"
 	fi
 
-	# Build optional JSON for json format tier
 	local _format="${post_scan_hook_format:-args}"
 	local _json_stdin=""
 	if [ "$_format" = "json" ]; then
 		_json_stdin=$(_scan_hook_build_json "$_scan_type")
 	fi
 
-	# Log dispatch and fire elog event
 	eout "{hook} ${_hook_type}-scan hook started: $_hook ($_exec, $_format)" 1
 	_lmd_elog_event "${ELOG_EVT_HOOK_STARTED:-hook_started}" "info" \
 		"hook started" \
 		"hook=$_hook" "type=$_scan_type" "exec=$_exec" "format=$_format"
 
-	# Route to sync or async executor
 	if [ "$_exec" = "sync" ]; then
 		_scan_hook_exec_sync "$_hook" "$_timeout" "$_scan_type" "$_json_stdin"
 	else

files/internals/lmd_init.sh

@@ -84,10 +84,8 @@ _resolve_hashtype() {
 
 _resolve_clamscan() {
 	# Normalize scan_clamscan from auto/0/1 to 0 or 1.
-	# When auto: enable if a clamscan binary is found on the system.
-	# Note: $clamscan is NOT set by internals.conf — it is populated later
+	# $clamscan is NOT set by internals.conf — it is populated later
 	# by clamselector()/clamscan_fallback(). We must discover it here.
-	# Writes resolved value back to scan_clamscan for all downstream code.
 	case "$scan_clamscan" in
 		auto)
 			if [ -f "/usr/local/cpanel/3rdparty/bin/clamscan" ] || [ -n "$(command -v clamscan 2>/dev/null)" ]; then
@@ -108,9 +106,7 @@ _resolve_clamscan() {
 
 _resolve_yara() {
 	# Normalize scan_yara from auto/0/1 to 0 or 1.
-	# When auto: enable only if ClamAV is unavailable AND a yara/yr binary exists.
-	# This prevents duplicate YARA evaluation — ClamAV already processes YARA rules.
-	# Writes resolved value back to scan_yara for all downstream code.
+	# Prevents duplicate YARA evaluation — ClamAV already processes YARA rules.
 	case "$scan_yara" in
 		auto)
 			if [ "$scan_clamscan" == "0" ] && { [ -n "$yara" ] || [ -n "$yr" ]; }; then