@@ -54,11 +54,11 @@
 (declare (uses dbmod))
 (import dbmod)
 
 (include "common_records.scm")
 
-
+;;======================================================================
 ;; (require-library margs)
 ;; (include "margs.scm")
 
 ;; (define old-exit exit)
 ;; 
@@ -79,10 +79,11 @@
 
 ;;======================================================================
 ;; L O C K I N G   M E C H A N I S M S 
 ;;======================================================================
 
+;;======================================================================
 ;; faux-lock is deprecated. Please use simple-lock below
 ;;
 (define (common:faux-lock keyname #!key (wait-time 8)(allow-lock-steal #t))
   (if (rmt:no-sync-get/default keyname #f) ;; do not be tempted to compare to pid. locking is a one-shot action, if already locked for this pid it doesn't actually count
       (if (> wait-time 0)
@@ -103,10 +104,11 @@
       (begin
         (if (rmt:no-sync-get/default keyname #f) (rmt:no-sync-del! keyname))
         #t)
       #f))
 
+;;======================================================================
 ;; simple lock. improve and converge on this one.
 ;;
 (define (common:simple-lock keyname)
   (rmt:no-sync-get-lock keyname))
 
@@ -123,11 +125,12 @@
     (debug:print-info 02 *default-log-port* "Running command: " fullcmd)
     (cond
      (with-vars     (common:without-vars  fullcmd))
      (with-orig-env (common:with-orig-env fullcmd))
      (else          (common:without-vars  fullcmd "MT_.*")))))
-		  
+
+;;======================================================================
 ;; ideally put all this info into the db, no need to preserve it across moving homehost
 ;;
 ;; return list of
 ;;  ( reachable? cpuload update-time )
 (define (common:get-host-info hostname)
@@ -155,10 +158,11 @@
             (alist-ref 'adj-core-load (common:get-normalized-cpu-load hostname)))) ;; this is cheaper than you might think. get-normalized-cpu-load is cached for up to 5 seconds
      (else
       (list #f 0 -1) ;; bad host, don't use!
       ))))
 
+;;======================================================================
 ;; see defstruct host at top of file.
 ;;    host: reachable last-update last-used last-cpuload
 ;;
 (define (common:update-host-loads-table hosts-raw)
   (let* ((hosts (filter (lambda (x)
@@ -179,10 +183,11 @@
          (host-reachable-set!    rec is-reachable)
          (host-last-update-set!  rec last-reached-time)
          (host-last-cpuload-set! rec load)))
      hosts)))
 
+;;======================================================================
 ;; hash-table tree to html list tree
 ;;
 ;;   tipfunc takes two parameters: y the tip value and path the path to that point
 ;;
 (define (common:htree->html ht path tipfunc)
@@ -204,10 +209,11 @@
 		       (list 
 			levelname
 			(common:htree->html y newpath tipfunc))))))
 	      datlist)))))
 
+;;======================================================================
 ;; logic for getting homehost. Returns (host . at-home)
 ;; IF *toppath* is not set, wait up to five seconds trying every two seconds
 ;; (this is to accomodate the watchdog)
 ;;
 (define (common:get-homehost #!key (trynum 5))
@@ -262,10 +268,11 @@
 			 (equal? homehost bestadrs))))
       (set! *home-host* (cons homehost at-home))
       (mutex-unlock! *homehost-mutex*)
       *home-host*))))
 
+;;======================================================================
 ;; am I on the homehost?
 ;;
 (define (common:on-homehost?)
   (let ((hh (common:get-homehost)))
     (if hh
@@ -274,10 +281,11 @@
 
 ;;======================================================================
 ;; D A S H B O A R D   U S E R   V I E W S
 ;;======================================================================
 
+;;======================================================================
 ;; first read ~/views.config if it exists, then read $MTRAH/views.config if it exists
 ;;
 (define (common:load-views-config)
   (let* ((view-cfgdat    (make-hash-table))
 	 (home-cfgfile   (conc (get-environment-variable "HOME") "/.mtviews.config"))
@@ -292,10 +300,11 @@
 ;;======================================================================
 ;; T A R G E T S  ,   S T A T E ,   S T A T U S ,   
 ;;                    R U N N A M E    A N D   T E S T P A T T
 ;;======================================================================
 
+;;======================================================================
 ;; (map print (map car (hash-table->alist (read-config "runconfigs.config" #f #t))))
 ;;
 (define (common:get-runconfig-targets #!key (configf #f))
   (let ((targs       (sort (map car (hash-table->alist
 				     (or configf ;; NOTE: There is no value in using runconfig:read here.
@@ -308,10 +317,11 @@
 	(filter (lambda (x)
 		  (patt-list-match x target-patt))
 		targs)
 	targs)))
 
+;;======================================================================
 ;; Lookup a value in runconfigs based on -reqtarg or -target
 ;; 
 (define (runconfigs-get config var)
   (let ((targ (common:args-get-target))) ;; (or (args:get-arg "-reqtarg")(args:get-arg "-target")(getenv "MT_TARGET"))))
     (if targ
@@ -416,10 +426,11 @@
       )
     )
 
   0)
 
+;;======================================================================
 ;; TODO: for multiple areas, we will have multiple watchdogs; and multiple threads to manage
 (define (common:watchdog)
   (debug:print-info 13 *default-log-port* "common:watchdog entered.")
   (if (launch:setup)
       (if (common:on-homehost?)
@@ -482,10 +493,11 @@
 	      (debug:print-error 0 *default-log-port* "Invalid target, spaces or blanks not allowed \"" target "\", target should be: " (string-intersperse keys "/") ", have " tlist " for elements")
 	      (if exit-if-bad (exit 1))
 	      #f)
 	    #f))))
 
+;;======================================================================
 ;; do we honor the caches of the config files?
 ;;
 (define (common:use-cache?)
   (let ((res #t)) ;; priority by order of evaluation
     (if *configdat* ;; sillyness here. can't use setup/use-cache to know if we can use the cached files!
@@ -498,11 +510,12 @@
 	(if (equal? (getenv "MT_USE_CACHE") "yes")
 	    (set! res #t)
 	    (if (equal? (getenv "MT_USE_CACHE") "no")
 		(set! res #f))))    ;; overrides -no-cache switch
     res))
-  
+
+;;======================================================================
 ;; force use of server?
 ;;
 (define (common:force-server?)
   (let* ((force-setting (configf:lookup *configdat* "server" "force"))
 	 (force-type    (if force-setting (string->symbol force-setting) #f))
@@ -537,10 +550,11 @@
 		 (not (get-environment-variable "MT_DEBUG_MODE"))))
 	(setenv "MT_DEBUG_MODE" (if (list? (verbosity))
 				    (string-intersperse (map conc (verbosity)) ",")
 				    (conc (verbosity)))))))
 
+;;======================================================================
 ;; go through the hosts from least recently used to most recently used, pick the first that meets the load criteral from the
 ;; [host-rules] section.
 ;;
 (define (common:get-least-loaded-host hosts-raw host-type configdat)
   (let* ((rdat       (configf:lookup configdat "host-rules" host-type))
@@ -602,17 +616,18 @@
 		    (debug:print 0 *default-log-port* "INFO: Found host: " new-best " load: " load " last-used: " delta " seconds ago, with job-rate: " job-rate)
 		    (host-last-used-set! rec curr-time)
 		    new-best)
 		  (if (null? tal) #f (loop (car tal)(cdr tal) best-host)))))))))
 
+;;======================================================================
 ;; '(print (string-intersperse (map cadr (hash-table-ref/default (read-config "megatest.config" \#f \#t) "disks" '"'"'("none" ""))) "\n"))'
 (define (common:get-disks #!key (configf #f))
   (hash-table-ref/default 
    (or configf (read-config "megatest.config" #f #t))
    "disks" '("none" "")))
 
-
+;;======================================================================
 ;; currently the primary job of the watchdog is to run the sync back to megatest.db from the db in /tmp
 ;; if we are on the homehost and we are a server (by definition we are on the homehost if we are a server)
 ;;
 (define (common:readonly-watchdog dbstruct)
   (thread-sleep! 0.05) ;; delay for startup
@@ -640,11 +655,11 @@
 			(debug:print-info 13 *default-log-port* "rosync called, " res " records transferred."))))
               (loop (current-seconds)))
             #t)))
     (debug:print-info 0 *default-log-port* "Exiting readonly-watchdog timer, *time-to-exit* = " *time-to-exit*" pid="(current-process-id)" mtpath="golden-mtpath)))
 
-
+;;======================================================================
 ;; Force a megatest cleanup-db if version is changed and skip-version-check not specified
 ;; Do NOT check if not on homehost!
 ;;
 (define (common:exit-on-version-changed)
   (if (common:on-homehost?)
@@ -683,15 +698,16 @@
               (debug:print 0 *default-log-port* "   You have read-only access to this area.  Cannot proceed with megatest version migration.")
               (exit 1))
              (else
               (debug:print 0 *default-log-port* " to switch versions you can run: \"megatest -cleanup-db\"")
               (exit 1)))))))
+;;======================================================================
 ;;      (begin
 ;;	(debug:print 0 *default-log-port* "ERROR: cannot migrate version unless on homehost. Exiting.")
 ;;	(exit 1))))
 
-        
+;;======================================================================
 ;; Rotate logs, logic: 
 ;;                 if > 500k and older than 1 week:
 ;;                     remove previous compressed log and compress this log
 ;; WARNING: This proc operates assuming that it is in the directory above the
 ;;          logs directory you wish to log-rotate.
@@ -773,10 +789,11 @@
 		      (debug:print-error 0 *default-log-port* "failed to remove " fullname ", exn=" exn)
 		      (delete-file* fullname)))))
 	     files)
 	    (debug:print-info 0 *default-log-port* "Deleted " (length files) " files from logs, keeping " max-allowed " files."))))))
   
+;;======================================================================
 ;; calculate a delay number based on a droop curve
 ;;    inputs are:
 ;;      - load-in, load as from uptime, NOT normalized
 ;;      - numcpus, number of cpus, ideally use the real cpus, not threads
 ;;
@@ -808,10 +825,11 @@
   (let loop ((x 0))
     (print x "," (common:get-delay x 1))
     (if (< x 2)
 	(loop (+ x 0.1)))))
 
+;;======================================================================
 ;; DO NOT CALL THIS DIRECTLY. It is called from common:wait-for-normalized-load
 ;;   count     - count down to zero, at some point we'd give up if the load never drops
 ;;   num-tries - count down to zero number tries to get numcpus
 ;;
 (define (common:wait-for-cpuload maxnormload numcpus-in
@@ -883,10 +901,11 @@
 	      (debug:print 0 *default-log-port* "Load on " effective-host " is acceptable at effective normalized load of "
 			   normalized-effective-load "  continuing."))
 	  (debug:print 0 *default-log-port* "Load on " effective-host ", "
 		       first" could not be retrieved. Giving up and continuing."))))))
 
+;;======================================================================
 ;; wait for normalized cpu load to drop below maxload
 ;;
 (define (common:wait-for-normalized-load maxnormload msg remote-host #!optional (rem-tries 5))
   (let ((num-cpus (common:get-num-cpus remote-host)))
     (if num-cpus
@@ -895,10 +914,11 @@
 	  (thread-sleep! (random 60)) ;; we failed to get num cpus. wait a bit and try again
 	  (if (> rem-tries 0)
 	      (common:wait-for-normalized-load maxnormload msg remote-host (- rem-tries 1))
 	      #f)))))
 
+;;======================================================================
 ;; given path get free space, allows override in [setup]
 ;; with free-space-script /path/to/some/script.sh
 ;;
 (define (get-df path)
   (if (configf:lookup *configdat* "setup" "free-space-script")
@@ -916,11 +936,10 @@
 		       0)))
     (list (> dbspace required)
 	  dbspace
 	  required
 	  dirpath)))
-
 
 (define (get-free-inodes path)
   (if (configf:lookup *configdat* "setup" "free-inodes-script")
       (with-input-from-pipe 
 	  (conc (configf:lookup *configdat* "setup" "free-inodes-script") " " path)
@@ -1033,10 +1052,11 @@
 	(let* ((pdb  (open-queue-db pdbpath "pkts.db"
 				    schema: '("CREATE TABLE groups (id INTEGER PRIMARY KEY,groupname TEXT, CONSTRAINT group_constraint UNIQUE (groupname));"))))
 	  (proc pktsdirs pktsdir pdb)
 	  (dbi:close pdb))))))
 
+;;======================================================================
 ;; check space in dbdir and in megatest dir
 ;; returns: ok/not dbspace required-space
 ;;
 (define (common:check-db-dir-space)
   (let* ((required (string->number 
@@ -1046,11 +1066,12 @@
 	 (dbdir    (common:get-db-tmp-area)) ;; (db:get-dbdir))
 	 (tdbspace (common:check-space-in-dir dbdir required))
 	 (mdbspace (common:check-space-in-dir *toppath* required)))
     (sort (list tdbspace mdbspace) (lambda (a b)
 				     (< (cadr a)(cadr b))))))
-    
+
+;;======================================================================
 ;; check available space in dbdir, exit if insufficient
 ;;
 (define (common:check-db-dir-and-exit-if-insufficient)
   (let* ((spacedat (car (common:check-db-dir-space))) ;; look only at worst for now
 	 (is-ok    (car spacedat))
@@ -1059,11 +1080,12 @@
 	 (dbdir    (cadddr spacedat)))
     (if (not is-ok)
 	(begin
 	  (debug:print-error 0 *default-log-port* "Insufficient space in " dbdir ", require " required ", have " dbspace  ", exiting now.")
 	  (exit 1)))))
-  
+
+;;======================================================================
 ;; paths is list of lists ((name path) ... )
 ;;
 (define (common:get-disk-with-most-free-space disks minsize)
   (let* ((best     #f)
 	(bestsize 0)
@@ -1116,10 +1138,11 @@
      (map car disks))
     (if (and best (> bestsize minsize))
 	best
 	#f))) ;; #f means no disk candidate found
 
+;;======================================================================
 ;; from metadat lookup MEGATEST_VERSION
 ;;
 (define (common:get-last-run-version) ;; RADT => How does this work in send-receive function??; assume it is the value saved in some DB
   (rmt:get-var "MEGATEST_VERSION"))
 
@@ -1128,10 +1151,11 @@
 
 (define (common:get-last-run-version-number)
   (string->number 
    (substring (common:get-last-run-version) 0 6)))
 
+;;======================================================================
 ;; postive number if megatest version > db version
 ;; negative number if megatest version < db version
 (define (common:version-db-delta)
          (- megatest-version (common:get-last-run-version-number)))
 
@@ -1141,11 +1165,11 @@
 
 (define (common:api-changed?)
   (not (equal? (substring (->string megatest-version) 0 4)
                (substring (conc (common:get-last-run-version)) 0 4))))
 
-
+;;======================================================================
 ;; Move me elsewhere ...
 ;; RADT => Why do we meed the version check here, this is called only if version misma
 ;;
 (define (common:cleanup-db dbstruct #!key (full #f))
   (apply db:multi-db-sync 
@@ -1161,10 +1185,12 @@
        ;; '())
        )
   (if (common:api-changed?)
       (common:set-last-run-version)))
 
+;;======================================================================
+;; use to transition to area-name
 (define common:get-area-name common:get-testsuite-name)
 
 (define (common:load-pkts-to-db mtconf #!key (use-lt #f))
   (common:with-queue-db
    mtconf
@@ -1197,10 +1223,11 @@
 		     )))
 	     pkts)))))
       pktsdirs))
    use-lt: use-lt))
 
+;;======================================================================
 ;; use-lt is use linktree "lt" link to find pkts dir
 (define (common:save-pkt pktalist-in mtconf use-lt #!key (add-only #f)) ;; add-only saves the pkt only if there is a parent already
   (if (or add-only
 	  (hash-table-exists? *pkts-info* 'last-parent))
       (let* ((parent   (hash-table-ref/default *pkts-info* 'last-parent #f))