From ed4efbb829bbf206fb1ff0b8dde27f2fa7cd3868 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 13 Oct 2026 14:59:12 +0000
Subject: [PATCH 1/4] fix(exec): follow-ups from independent review of
 #304/#306/#290
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Stale-lock takeover serialised through an O_EXCL .exec.lock.takeover file;
  the lock is removed only if it still holds the stale line read (no mv -f
  restore). 12 contenders x 10 rounds: master 2/10 rounds with 2-3 holders,
  fixed 0/10.
- --watch-compat: only ui-loop.md's watch-safe list says "watch can apply
  this"; other statements print "unknown — restart if behaviour looks stale".
- Two-tree (.mpr under app/) cases for the lock and --commit-first.
- Leading flags parsed in one loop (--commit-first --cr CR-NN works); a
  script name starting with -- is refused before any commit or snapshot.
- ui-only test lane names the embedders of a changed snippet/layout.

Refs #287 #289 #274

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 CHANGELOG.md                          |   1 +
 project-bin/exec.sh                   | 169 ++++++++++++++++++--------
 tests/wave2/test-exec-change-class.sh |   8 ++
 tests/wave2/test-exec-lock-watch.sh   | 128 +++++++++++++++++++
 4 files changed, 254 insertions(+), 52 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 20342404..543b3aeb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are.
 
 ## Unreleased
 
+- fix(exec): **follow-ups from an independent review of #304/#306/#290: the stale-lock takeover is mutually exclusive, only watch-safe statements say "watch can apply this", `--cr` works after `--commit-first`, and the ui-only test lane names snippet/layout embedders** ([#287](https://github.com/MendixMau/mxcli-project-toolkit/issues/287), [#289](https://github.com/MendixMau/mxcli-project-toolkit/issues/289), [#274](https://github.com/MendixMau/mxcli-project-toolkit/issues/274)). (1) The takeover moved a stale lock aside and put back a fresh one with `mv -f`, which is check-then-act: with 12 contenders against one dead-pid lock, up to 3 held the lock at once. It is now serialised through an O_EXCL `.exec.lock.takeover` file (bounded by pid and age), and the lock is removed only if it still holds the stale line that was read. `tests/wave2/test-exec-lock-watch.sh` runs 10 rounds of 12 contenders and asserts at most one holder. On master 2 of 10 rounds had 2 or 3 holders; with the fix, 0. (2) `--watch-compat` said "watch can apply this" for any statement it did not classify: associations, enumerations, `ALTER ENTITY … MODIFY`, Java actions, constants and navigation. These now print `unknown — restart if behaviour looks stale`, and only statements on ui-loop.md's watch-safe list say watch can apply them. (3) The fixture now also covers a two-tree checkout (`.mpr` under `app/`) for the lock and `--commit-first`. (4) Leading flags are parsed in one loop and can come in any order. The documented `--commit-first --cr CR-07 <script>` used to commit the model and then run "--cr" as the script. A script name starting with `--` is now refused before any commit or snapshot. (5) The ui-only lane now says "journeys of every page the change reaches (embedders of a changed snippet/layout)" instead of "no other module's journeys". — MendixMau
 - learn(testing-shape, test-result-audit): **three test-strength rules, each with a denominator: refusals probed on the server, every undeclared 4xx a failure, one clean-database final run** ([#172](https://github.com/MendixMau/mxcli-project-toolkit/issues/172)). A field comparison of two builds against one frozen spec found the toolkit build checked permission refusals only in the client (a hidden menu item), logged unexpected 400/422 responses as information, and reached 20/20 by stitching three runs. `testing-shape.md` §7 gains three report lines (`N of N restricted pairs probed server-side`, `undeclared 4xx/5xx: 0 of M requests — each fails its step`, `one clean-DB run <id>: N of N scenarios incl. timers, not stitched`); `test-result-audit.md` gains check 2e, which carries the reasons and the field evidence and asks for those numbers. Both baseline skills stay inside the 80,000-word baseline budget (79,997): the reasons live in the on-demand audit skill, and two redundant sentences in `testing-shape.md` §4's verdict paragraphs were folded (the empty-set corollary is stated in the Trace row, `harness-architecture.md` and `report-schema.md`). The backing inbox note is trimmed to its unpromoted "Keep" items. — MendixMau
 - learn(learned-detection-gaps, module-review): **two UI defects every model gate passes: a lazy-loaded combo box filter hides its preset, and a theme that pins row heights by position lets the next row cover an inserted widget** ([#299](https://github.com/MendixMau/mxcli-project-toolkit/issues/299)). Both passed check, mxbuild, lint and the scripted checks on a 127-module production app and were found only in the running app. Two register rows with the first oracle and the pre-build check (pluggable properties that change *when* data loads; grep the theme for fixed `height` on positional row classes before an insert), and two LOOK lines in `module-review.md` §4c with denominators (`N of N filters show their preset on first load`, `N of N widgets inserted into an existing container fully visible`). — jopterhorst
 - fix(app-restart, test-stack-up): **a port held by another process before `run --local` is named and reported as "instrument blocked" (exit 4), never killed** ([#262](https://github.com/MendixMau/mxcli-project-toolkit/issues/262)). Studio Pro had started its own runtime on the app/admin ports a restart needed; `mxcli run --local` then failed with "Authentication failed" (the admin API answering was Studio Pro's), the next journey ran against Studio Pro's runtime, and four more runs were NOT RUN. `app-restart.sh` now checks the app port and the admin port (record's `adminPort`, else app + 10) before stopping anything — a holder outside the recorded process tree exits 4 with its name, pid and parent — and again after the stop, where anything still holding a port is by definition not ours. `test-stack-up.sh` runs the same check wherever it would tell you to start `run --local` (`--no-docker`, no Docker daemon, `--check` with a leftover record), on the record's ports, `RUN_LOCAL_APP_PORT`/`RUN_LOCAL_ADMIN_PORT`, or mxcli's defaults 8080/8090. Holder lookup: lsof, then ss, then netstat + tasklist on Windows; unnamed holders still block when nothing of ours is running. Fixtures: `test-app-restart.sh` +2 cases (14 assertions, all fail on the old script), `test-stack-up-local.sh` T7 (4 of 6 fail on the old script). — AlvinnYeo
diff --git a/project-bin/exec.sh b/project-bin/exec.sh
index dd25f3c1..9fbe82ff 100755
--- a/project-bin/exec.sh
+++ b/project-bin/exec.sh
@@ -17,6 +17,7 @@
 #        ./bin/exec.sh --watch-compat <script.mdl>   (advisory: can `run --local --watch` apply
 #                                                     this, or does the app need a restart; writes nothing)
 #        ./bin/exec.sh --cr CR-07 <script.mdl>        (any mode: tag the run with its change request)
+#        Leading flags (--cr, --commit-first, then --patch) may come in any order.
 #
 # --cr (2026-10-13): names the PROJECT.md "## Change log" row this run applies
 # (skills/change-intake.md). It lands in the BUILD-LOG detail cell as "cr: CR-07", the same way
@@ -162,24 +163,43 @@ mxtk_change_class() {  # $1 = MDL script; prints "<class>\t<why>"
       printf "ui-only\t%d page/snippet/layout statement(s), nothing else\n", ui
     }' "$1"
 }
-# --cr CR-NN may lead any mode. Parsed first, before anything needs a project, so a malformed id
-# is refused without touching the model.
-CR_ID=""
-if [ "${1:-}" = "--cr" ]; then
-  CR_ID="${2:-}"
-  case "$CR_ID" in
-    CR-[0-9]*) case "${CR_ID#CR-}" in *[!0-9]*) CR_ID="!" ;; esac ;;
-    *) CR_ID="!" ;;
+# Leading flags, parsed in ONE loop before anything needs a project, in any order:
+# --cr CR-NN, --commit-first, then optionally --patch (whose next word is the script) or one of
+# the advisory modes. A malformed --cr id, an unknown --flag, or a script name starting with
+# `--` is refused here, before the lock, the commit or the snapshot. WHY (review of #306): --cr
+# was only honoured as the FIRST argument, though the usage line documents
+# `[--commit-first] [--cr CR-NN]`; in that order commit-first committed the model and the run
+# went on with "--cr" as its script path.
+CR_ID=""; COMMIT_FIRST="${MXTK_COMMIT_FIRST:-0}"; PATCH_MODE=0; ADVISORY=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --cr)
+      CR_ID="${2:-}"
+      case "$CR_ID" in
+        CR-[0-9]*) case "${CR_ID#CR-}" in *[!0-9]*) CR_ID="!" ;; esac ;;
+        *) CR_ID="!" ;;
+      esac
+      if [ "$CR_ID" = "!" ]; then
+        echo "✗ --cr takes a change-log id like CR-07 (PROJECT.md '## Change log', skills/change-intake.md); got '${2:-}'" >&2
+        exit 2
+      fi
+      shift 2 ;;
+    --commit-first) COMMIT_FIRST=1; shift ;;
+    --patch) PATCH_MODE=1; shift; break ;;
+    --change-class|--watch-compat) ADVISORY="$1"; shift; break ;;
+    *) break ;;
   esac
-  if [ "$CR_ID" = "!" ]; then
-    echo "✗ --cr takes a change-log id like CR-07 (PROJECT.md '## Change log', skills/change-intake.md); got '${2:-}'" >&2
-    exit 2
-  fi
-  shift 2
-fi
-if [ "${1:-}" = "--change-class" ]; then
-  [ -f "${2:-}" ] || { echo "Usage: ./bin/exec.sh --change-class <script.mdl>" >&2; exit 2; }
-  mxtk_change_class "$2"
+done
+case "${1:-}" in
+  --*)
+    echo "✗ Unknown option or misplaced flag '$1' — nothing was committed, snapshotted or executed." >&2
+    echo "  Usage: ./bin/exec.sh [--commit-first] [--cr CR-NN] <script.mdl>" >&2
+    echo "         ./bin/exec.sh [--commit-first] [--cr CR-NN] --patch <script> [args...]" >&2
+    exit 2 ;;
+esac
+if [ "$ADVISORY" = "--change-class" ]; then
+  [ -f "${1:-}" ] || { echo "Usage: ./bin/exec.sh --change-class <script.mdl>" >&2; exit 2; }
+  mxtk_change_class "$1"
   exit 0
 fi
 
@@ -204,6 +224,13 @@ fi
 #   CREATE ... MODULE ROLE | USER ROLE, ALTER USER ROLE      → role added/changed
 #   CREATE PAGE (no OR — a new page)                         → new page
 #   a Url property on a page (create header, `set Url = ...`) → page URL (route table)
+# Watch-safe (the ONLY statements reported `watch can apply this`, ui-loop.md's left column):
+#   ALTER PAGE / ALTER SNIPPET, CREATE [OR ...] SNIPPET, CREATE OR REPLACE|MODIFY PAGE (no Url).
+# Read-only heads (SHOW, DESCRIBE, ...) are neutral. Any other statement — CREATE ASSOCIATION,
+# CREATE ENUMERATION, ALTER ENTITY ... MODIFY, a Java action, a constant, navigation, DROP PAGE,
+# UPDATE WIDGETS — is on neither column and prints `unknown — restart if behaviour looks stale`
+# (independent review of #304: these all used to say "watch can apply this", a claim nobody had
+# checked).
 # `CREATE OR REPLACE|MODIFY PAGE` without a Url is reported as reloadable, with a note that
 # it needs a restart IF the page is new — a script cannot tell new from replaced. Theme
 # SCSS/JS is not in the script; exec.sh checks those files against the running app's boot
@@ -212,32 +239,34 @@ fi
 # ADVISORY ONLY: never blocks, never changes a gate or a verdict. Golden input: real MDL
 # (tests/wave2/test-exec-lock-watch.sh).
 #
-#   ./bin/exec.sh --watch-compat <script.mdl>   prints `restart needed: <reasons>` or
-#                                               `watch can apply this`, exit 0. Touches nothing.
-mxtk_watch_compat() {  # $1 = MDL script; prints "restart\t<reasons>" | "watch\t<note>"
+#   ./bin/exec.sh --watch-compat <script.mdl>   prints `restart needed: <reasons>`,
+#                                               `unknown — restart if behaviour looks stale: <heads>`
+#                                               or `watch can apply this`, exit 0. Touches nothing.
+mxtk_watch_compat() {  # $1 = MDL script; prints "restart\t<reasons>" | "unknown\t<heads>" | "watch\t<note>"
   awk "$_MXTK_MDL_LEX"'
     function add(label, nr) {
       if (!(label in cnt)) { order[++nlab] = label; first[label] = nr }
       cnt[label]++
     }
-    BEGIN { depth = 0; inblock = 0; indollar = 0; cur_page = 0; nlab = 0; maybe = "" }
+    BEGIN { depth = 0; inblock = 0; indollar = 0; cur_page = 0; nlab = 0; maybe = ""; unk = ""; nunk = 0 }
     {
       lex_line($0)
       t = clean; gsub(/^[ \t]+/, "", t)
       if (start_depth == 0 && t ~ /^[A-Za-z]/) {
         n = split(toupper(t), w, /[ \t(;{]+/)
         v = w[1]
-        if (v ~ /^(CREATE|ALTER|DROP|GRANT|REVOKE|MOVE|RENAME|SHOW|DESCRIBE|UPDATE|SET|EXECUTE)$/) {
+        if (v ~ /^(CREATE|ALTER|DROP|MOVE|GRANT|REVOKE|UPDATE|INSERT|DELETE|SQL|IMPORT|EXPORT|EXECUTE|RENAME|SET|CALL|COMMIT|CHANGE|RETRIEVE|DECLARE)$/) {
           j = 2; if (v == "CREATE" && w[2] == "OR") j = 4
           o1 = w[j]; o2 = w[j+1]; o3 = w[j+2]
           cur_page = ((v == "CREATE" || v == "ALTER") && o1 == "PAGE")
+          attr = 0
+          if (v == "ALTER" && o1 == "ENTITY") for (k = 3; k <= n; k++) if (w[k] == "ADD") { attr = 1; break }
           if ((v == "CREATE" || v == "DROP") && o1 == "MICROFLOW")
             add(v == "DROP" ? "microflow dropped" : "microflow created or recreated", NR)
           else if (v == "CREATE" && (o1 == "ENTITY" || o2 == "ENTITY"))
             add("entity created or changed (new attributes)", NR)
-          else if (v == "ALTER" && o1 == "ENTITY") {
-            for (k = 3; k <= n; k++) if (w[k] == "ADD") { add("attribute added", NR); break }
-          }
+          else if (attr)
+            add("attribute added", NR)
           else if (v == "GRANT" || v == "REVOKE")
             add("access rule changed (" v ")", NR)
           else if ((v == "CREATE" && ((o1 == "MODULE" && o2 == "ROLE") || (o1 == "USER" && o2 == "ROLE"))) \
@@ -245,8 +274,18 @@ mxtk_watch_compat() {  # $1 = MDL script; prints "restart\t<reasons>" | "watch\t
             add("module/user role added or changed", NR)
           else if (v == "CREATE" && o1 == "PAGE" && j == 2)
             add("new page", NR)
-          else if (v == "CREATE" && o1 == "PAGE" && maybe == "")
-            maybe = "line " NR ": " substr(t, 1, 60)
+          else if (v == "CREATE" && o1 == "PAGE") {
+            if (maybe == "") maybe = "line " NR ": " substr(t, 1, 60)
+          }
+          # The watch-safe list (skills/ui-loop.md "What watch picks up", left column): an
+          # ALTER PAGE / ALTER SNIPPET edit, a new or changed snippet. Everything else that is
+          # not on either column is UNKNOWN, never "watch can apply this".
+          else if ((v == "ALTER" && (o1 == "PAGE" || o1 == "SNIPPET")) || (v == "CREATE" && o1 == "SNIPPET"))
+            ;
+          else if (nunk < 3) {
+            h = t; if (length(h) > 50) h = substr(h, 1, 50) "..."
+            unk = unk (nunk++ ? "; " : "") "line " NR ": " h
+          } else nunk++
         }
       }
       # A Url property on a page: the create header `(..., Url: ...)` or `set Url = ...` in an
@@ -261,15 +300,17 @@ mxtk_watch_compat() {  # $1 = MDL script; prints "restart\t<reasons>" | "watch\t
         }
         printf "restart\t%s\n", s; exit
       }
+      if (nunk > 0) { printf "unknown\t%s%s\n", unk, (nunk > 3 ? " (+" (nunk - 3) " more)" : ""); exit }
       if (maybe != "") { printf "watch\tunless the page is new: create or replace/modify page, %s\n", maybe; exit }
       printf "watch\t\n"
     }' "$1"
 }
-if [ "${1:-}" = "--watch-compat" ]; then
-  [ -f "${2:-}" ] || { echo "Usage: ./bin/exec.sh --watch-compat <script.mdl>" >&2; exit 2; }
-  _wc="$(mxtk_watch_compat "$2")"
+if [ "$ADVISORY" = "--watch-compat" ]; then
+  [ -f "${1:-}" ] || { echo "Usage: ./bin/exec.sh --watch-compat <script.mdl>" >&2; exit 2; }
+  _wc="$(mxtk_watch_compat "$1")"
   case "${_wc%%	*}" in
     restart) echo "restart needed: ${_wc#*	}" ;;
+    unknown) echo "unknown — restart if behaviour looks stale: ${_wc#*	}" ;;
     *) _n="${_wc#*	}"
        if [ -n "$_n" ]; then echo "watch can apply this — $_n"; else echo "watch can apply this"; fi ;;
   esac
@@ -281,16 +322,6 @@ fi
 MPR="$(find_mpr)" || exit 1
 MPR_BASE="$(basename "$MPR")"
 NAME="$(basename "$MPR" .mpr)"
-PATCH_MODE=0
-COMMIT_FIRST="${MXTK_COMMIT_FIRST:-0}"
-if [ "${1:-}" = "--commit-first" ]; then
-  COMMIT_FIRST=1
-  shift
-fi
-if [ "${1:-}" = "--patch" ]; then
-  PATCH_MODE=1
-  shift
-fi
 SCRIPT="${1:-}"
 [ $# -gt 0 ] && shift
 # Remaining args go to the patch script, after the model path. An MDL run takes none.
@@ -299,7 +330,7 @@ LOG_NAME="$(basename "$SCRIPT")"
 
 if [ -z "$SCRIPT" ]; then
   echo "Usage: ./bin/exec.sh [--commit-first] [--cr CR-NN] <script.mdl>"
-  echo "       ./bin/exec.sh [--commit-first] --patch <script> [args...]"
+  echo "       ./bin/exec.sh [--commit-first] [--cr CR-NN] --patch <script> [args...]"
   exit 1
 fi
 if [ "$PATCH_MODE" = "1" ]; then
@@ -324,7 +355,7 @@ elif [ -r "$SCRIPT" ]; then
 fi
 change_lane() {
   case "$CHANGE_CLASS" in
-    ui-only) echo "re-run this change's own journey once + a LOOK. No .test.mdl, no other module's journeys; reviewers read the artifacts, they do not re-run" ;;
+    ui-only) echo "re-run the journeys of every page the change reaches (embedders of a changed snippet/layout) once + a LOOK. No .test.mdl; reviewers read the artifacts, they do not re-run" ;;
     logic)   echo "re-run only the tests whose subject this change touched (changed microflows + their SHOW CALLERS, changed pages' journeys). Full mxcli test at module close, not here" ;;
   esac
 }
@@ -497,8 +528,42 @@ exec_lock_release() {  # the trap: remove the lock only while it is still ours
   [ "${_own%% *}" = "$$" ] && rm -f "$LOCK"
   return 0
 }
+# Taking over a stale lock is serialised through a second O_EXCL file, $LOCK.takeover. Under
+# it the lock is re-read and removed ONLY if it still holds exactly the stale line judged above;
+# nothing else ever removes a lock that is not its own, so the compare-then-rm cannot hit a
+# fresh lock. WHY (independent review of #304): the old takeover moved the lock aside and put
+# it back with `mv -f` when it found a fresh one there — check-then-act. With 3+ contenders, B
+# moved A's fresh lock aside, C's noclobber write landed in the gap, B saw a lock and deleted
+# A's: 12 contenders gave up to 3 holders at once (tests/wave2/test-exec-lock-watch.sh).
+# A takeover file left by a holder killed inside those few microseconds is stale once its pid is
+# dead or it is older than 10 s (an EMPTY one once it is a minute old); it is moved aside, and put back with `ln` (fails if a new one
+# exists — never clobbers) if what was moved is not the one judged stale.
+exec_lock_takeover() {  # $1 = the stale lock line; 0 iff it was removed (or already gone)
+  _tk="$LOCK.takeover"
+  if ! ( set -o noclobber; printf '%s %s\n' "$$" "$(date +%s)" > "$_tk" ) 2>/dev/null; then
+    _t="$(head -1 "$_tk" 2>/dev/null || true)"; _tpid="${_t%% *}"; _tsince="${_t#* }"
+    case "$_tsince" in ''|*[!0-9]*) _tsince=0 ;; esac
+    _tstale=0
+    if [ -n "$_t" ]; then
+      { ! kill -0 "$_tpid" 2>/dev/null || [ $(( $(date +%s) - _tsince )) -gt 10 ]; } && _tstale=1
+    elif [ -n "$(find "$_tk" -mmin +0 2>/dev/null)" ]; then
+      _tstale=1   # empty for a minute: its creator died between the create and the write
+    fi
+    if [ "$_tstale" = 1 ]; then
+      if mv "$_tk" "$_tk.stale.$$" 2>/dev/null; then
+        [ "$(head -1 "$_tk.stale.$$" 2>/dev/null || true)" = "$_t" ] || ln "$_tk.stale.$$" "$_tk" 2>/dev/null || true
+        rm -f "$_tk.stale.$$"
+      fi
+    fi
+    return 1
+  fi
+  _now="$(head -1 "$LOCK" 2>/dev/null || true)"
+  [ "$_now" = "$1" ] && rm -f "$LOCK"
+  rm -f "$_tk"
+  return 0
+}
 LOCK_TAKEN=0
-for _try in 1 2 3 4 5; do
+for _try in 1 2 3 4 5 6; do
   if exec_lock_try; then LOCK_TAKEN=1; break; fi
   _held="$(head -1 "$LOCK" 2>/dev/null || true)"
   if [ -z "$_held" ] && [ "$_try" -lt 3 ]; then sleep 1; continue; fi   # being written right now
@@ -513,18 +578,14 @@ for _try in 1 2 3 4 5; do
     echo "    (A dead holder is detected and taken over automatically — no manual rm is ever needed.)"
     exit 1
   fi
-  echo "  (stale exec lock from PID ${_hpid:-?}, which is not running — taking it over)"
-  # Move aside only the lock we judged; if someone else replaced it in between, put theirs back.
-  _aside="$LOCK.stale.$$"
-  if mv -f "$LOCK" "$_aside" 2>/dev/null; then
-    if [ "$(head -1 "$_aside" 2>/dev/null || true)" != "$_held" ] && [ ! -e "$LOCK" ]; then
-      mv -f "$_aside" "$LOCK" 2>/dev/null || true
-    fi
-    rm -f "$_aside"
+  if exec_lock_takeover "$_held"; then
+    echo "  (stale exec lock from PID ${_hpid:-?}, which is not running — taking it over)"
+  else
+    sleep 1   # another contender is taking it over right now; look again
   fi
 done
 if [ "$LOCK_TAKEN" != 1 ]; then
-  echo "✗ Could not take the exec lock $LOCK after 5 attempts — another session keeps re-taking it."
+  echo "✗ Could not take the exec lock $LOCK after 6 attempts — another session keeps re-taking it."
   echo "  → Wait for the other exec to finish, then re-run. Nothing was written."
   exit 1
 fi
@@ -1558,6 +1619,10 @@ print_watch_compat() {
       echo "→ Watch: restart needed: $_why"
       echo "  run --local --watch keeps serving the OLD model for these. Restart this app only:"
       echo "  ./bin/app-restart.sh   (stale-runtime symptoms + what watch covers: toolkit skills/ui-loop.md)" ;;
+    unknown)
+      echo "→ Watch: unknown — restart if behaviour looks stale: $_why"
+      echo "  Not on the watch-safe list (toolkit skills/ui-loop.md \"What watch picks up\"); if the app"
+      echo "  still behaves as before this change: ./bin/app-restart.sh" ;;
     watch)
       if [ -n "$_why" ]; then echo "→ Watch: watch can apply this — $_why"
       else echo "→ Watch: watch can apply this"; fi ;;
diff --git a/tests/wave2/test-exec-change-class.sh b/tests/wave2/test-exec-change-class.sh
index f43de319..c6f30cab 100755
--- a/tests/wave2/test-exec-change-class.sh
+++ b/tests/wave2/test-exec-change-class.sh
@@ -81,6 +81,14 @@ grep -q 'change class: \$CHANGE_CLASS — test lane' "$SUBJECT" && ok "success s
                                                            || bad "summary does not print the change class"
 grep -q 'testing-shape.md' "$SUBJECT" && ok "the lane text points at testing-shape.md" \
                                       || bad "no pointer to testing-shape.md"
+# A changed snippet or layout is shown on every page that embeds it, so its ui-only lane is those
+# pages' journeys — not "no other module's journeys" (independent review of #290).
+_lane="$(grep -E '^ +ui-only\) echo' "$SUBJECT")"
+case "$_lane" in
+  *"no other module's journeys"*) bad "ui-only lane still says 'no other module's journeys' (wrong for a snippet/layout)" ;;
+  *"embedders of a changed snippet/layout"*) ok "ui-only lane names the embedders of a changed snippet/layout" ;;
+  *) bad "ui-only lane text not found or does not name embedders: $_lane" ;;
+esac
 # The metrics ledger is 19 fixed columns (test-metrics-ledger.sh asserts it); the tag must not
 # be smuggled into it as a 20th.
 grep -qiE 'change[_ -]class' "$(dirname "$SUBJECT")/metrics-ledger.sh" 2>/dev/null \
diff --git a/tests/wave2/test-exec-lock-watch.sh b/tests/wave2/test-exec-lock-watch.sh
index a448dfd6..29c8c6c5 100755
--- a/tests/wave2/test-exec-lock-watch.sh
+++ b/tests/wave2/test-exec-lock-watch.sh
@@ -55,6 +55,9 @@ mkproj() {  # $1 = dir
 set -e
 cd "$(dirname "$0")/.."
 sleep "${SNAP_SLEEP:-0}"
+if [ -n "${CS_DIR:-}" ]; then   # critical-section probe for the race case: who else is in here?
+  : > "$CS_DIR/in.$$"; ls "$CS_DIR" | grep -c '^in\.' >> "$CS_DIR/counts"; sleep 0.3; rm -f "$CS_DIR/in.$$"
+fi
 D=".mpr-snapshots/$(date +%Y%m%d-%H%M%S)-$$"
 mkdir -p "$D"; cp Fixture.mpr "$D/"; cp -r mprcontents "$D/"
 echo "Snapshot saved: $D"
@@ -114,6 +117,47 @@ has "takeover is said out loud" "$OUT" "taking it over"
 has "the run actually wrote" "$OUT" "fake mxcli exec"
 [ -f "$LOCK" ] && bad "lock left behind after a clean run" || ok "lock removed after the run"
 
+echo "-- lock: 12 contenders against one stale lock — never more than one holder (#304 review)"
+# The takeover used to move the stale lock aside and put it back with mv -f when it found a
+# fresh one: check-then-act. With >=3 contenders, B moved A's fresh lock aside, C's noclobber
+# write landed in the gap, B saw -e $LOCK and deleted A's lock — up to 3 holders at once.
+RACE_BAD=0; RACE_ENTERED=0; ROUNDS=10; N=12
+for round in $(seq 1 $ROUNDS); do
+  CS="$WORK/cs.$round"; mkdir -p "$CS"; GO="$WORK/go.$round"
+  printf '%s 1700000000 old.mdl\n' "$(dead_pid)" > "$LOCK"
+  PIDS=""
+  for c in $(seq 1 $N); do
+    ( cd "$P" && while [ ! -e "$GO" ]; do sleep 0.01; done
+      exec env CS_DIR="$CS" SKIP_BASELINE=1 SP_RESTART=0 MXTK_NO_INSTALL=1 MXTK_NO_SCORE=1 \
+        MXBUILD_PATH="$WORK/mxbuild" ./bin/exec.sh mdlsource/test.mdl ) >"$CS/out.$c" 2>&1 &
+    PIDS="$PIDS $!"
+  done
+  sleep 0.3; : > "$GO"
+  for p in $PIDS; do wait "$p" 2>/dev/null; done
+  [ -s "$CS/counts" ] && RACE_ENTERED=$((RACE_ENTERED+1))
+  _max="$(sort -n "$CS/counts" 2>/dev/null | tail -1)"
+  if [ "${_max:-0}" -gt 1 ]; then RACE_BAD=$((RACE_BAD+1)); echo "    round $round: $_max holders at once"; fi
+  rm -f "$LOCK" "$LOCK.takeover"
+done
+[ "$RACE_ENTERED" -eq "$ROUNDS" ] && ok "[setup] a contender took the stale lock in every round" \
+  || bad "[setup] only $RACE_ENTERED/$ROUNDS rounds had any holder — case proves nothing"
+[ "$RACE_BAD" -eq 0 ] && ok "never more than one holder across $ROUNDS rounds of $N contenders" \
+  || bad "$RACE_BAD/$ROUNDS rounds had more than one holder in the critical section"
+ls "$P/.mpr-snapshots/" | grep -q '\.stale\.' && bad "a .stale.<pid> aside file was left behind" || ok "no aside files left behind"
+
+echo "-- lock: a takeover file left by a killed contender does not block (instrument rule 7)"
+printf '%s 1700000000 old.mdl\n' "$(dead_pid)" > "$LOCK"
+printf '%s %s\n' "$(dead_pid)" "$(date +%s)" > "$LOCK.takeover"
+OUT="$(run "$P" mdlsource/test.mdl)"; RC=$?
+[ "$RC" -eq 0 ] && has "dead-pid takeover file cleared, stale lock taken over" "$OUT" "taking it over" \
+  || bad "a dead contender's takeover file blocked (rc $RC): $(printf '%s' "$OUT" | tail -3)"
+[ -e "$LOCK.takeover" ] && bad "takeover file left behind" || ok "takeover file gone after the run"
+printf '%s 1700000000 old.mdl\n' "$(dead_pid)" > "$LOCK"
+: > "$LOCK.takeover"; touch -t 202601010000 "$LOCK.takeover"
+OUT="$(run "$P" mdlsource/test.mdl)"; RC=$?
+[ "$RC" -eq 0 ] && ok "an empty takeover file older than a minute is stale too" || bad "empty old takeover file blocked (rc $RC)"
+rm -f "$LOCK.takeover"
+
 echo "-- lock: old bare-pid format, dead pid"
 dead_pid > "$LOCK"
 OUT="$(run "$P" mdlsource/test.mdl)"; RC=$?
@@ -170,6 +214,65 @@ hasnt "nothing executed" "$OUT" "fake mxcli exec"
 kill -KILL "$SP" 2>/dev/null; wait "$SP" 2>/dev/null; rm -f "$P/Fixture.mpr.lock"
 ( cd "$P" && git checkout -q -- mprcontents )
 
+echo "-- leading flags in any order (#306 review): --commit-first --cr CR-NN <script>"
+printf 'cr edit\n' >> "$P/mprcontents/a.mxunit"
+HEAD2="$(git -C "$P" rev-parse HEAD)"
+OUT="$(run "$P" --commit-first --cr CR-07 mdlsource/test.mdl)"; RC=$?
+[ "$RC" -eq 0 ] && ok "documented order ran (rc 0)" || bad "--commit-first --cr failed (rc $RC): $(printf '%s' "$OUT" | tail -4)"
+has "the CR tag was honoured" "$OUT" "Change request: CR-07"
+has "the script that ran is the real one" "$OUT" "fake mxcli exec"
+tail -1 "$P/docs/BUILD-LOG.md" 2>/dev/null | grep -q 'cr: CR-07' && ok "BUILD-LOG row carries cr: CR-07" \
+  || bad "BUILD-LOG row: $(tail -1 "$P/docs/BUILD-LOG.md" 2>/dev/null)"
+[ "$(git -C "$P" rev-list --count "$HEAD2"..HEAD)" = 1 ] && ok "exactly one model commit made" || bad "commits made: $(git -C "$P" rev-list --count "$HEAD2"..HEAD)"
+printf 'flag edit\n' >> "$P/mprcontents/a.mxunit"
+HEAD3="$(git -C "$P" rev-parse HEAD)"; NSNAP="$(ls "$P/.mpr-snapshots" | grep -c .)"
+OUT="$(run "$P" --commit-first --bogus mdlsource/test.mdl)"; RC=$?
+[ "$RC" -eq 2 ] && ok "a script name starting with -- is refused (rc 2)" || bad "misplaced flag: rc $RC"
+has "  and named" "$OUT" "'--bogus'"
+[ "$(git -C "$P" rev-parse HEAD)" = "$HEAD3" ] && ok "  before commit-first committed anything" || bad "commit-first committed before the refusal"
+[ "$(ls "$P/.mpr-snapshots" | grep -c .)" = "$NSNAP" ] && ok "  and before any snapshot" || bad "a snapshot was taken before the refusal"
+hasnt "  and nothing executed" "$OUT" "fake mxcli exec"
+( cd "$P" && git checkout -q -- mprcontents )
+
+echo "-- two-tree checkout (.mpr under app/): lock and --commit-first (#304 review; CLAUDE.md field-proof rule 2)"
+T="$WORK/twotree"; mkproj "$T"
+( cd "$T" && mkdir app && git mv Fixture.mpr app/ && git mv mprcontents app/ \
+  && git -c user.email=t@t -c user.name=t commit -qm two-tree ) >/dev/null 2>&1
+cat > "$T/bin/snapshot-mpr.sh" <<'SNAP2'
+#!/usr/bin/env bash
+set -e
+cd "$(dirname "$0")/.."
+sleep "${SNAP_SLEEP:-0}"
+D=".mpr-snapshots/$(date +%Y%m%d-%H%M%S)-$$"
+mkdir -p "$D"; cp app/Fixture.mpr "$D/"; cp -r app/mprcontents "$D/"
+echo "Snapshot saved: $D"
+SNAP2
+chmod +x "$T/bin/snapshot-mpr.sh"
+TLOCK="$T/.mpr-snapshots/.exec.lock"
+[ -f "$T/app/Fixture.mpr" ] && [ ! -e "$T/Fixture.mpr" ] && ok "[setup] model only under app/" || bad "[setup] two-tree layout not built"
+H2="$(bg_hold "$T")"; BG_PIDS="$BG_PIDS $H2"
+if wait_lock "$TLOCK"; then
+  ok "the lock lives at the project root (.mpr-snapshots/.exec.lock), not under app/"
+  OUT="$(run "$T" mdlsource/test.mdl)"; RC=$?
+  [ "$RC" -ne 0 ] && has "a second exec is refused on a two-tree checkout" "$OUT" "PID $H2" || bad "two-tree: second exec ran concurrently"
+else
+  bad "two-tree: background exec never took the lock at $TLOCK"
+fi
+kill -KILL "$H2" 2>/dev/null; wait "$H2" 2>/dev/null
+OUT="$(run "$T" mdlsource/test.mdl)"; RC=$?
+[ "$RC" -eq 0 ] && has "two-tree: the SIGKILLed holder's lock is taken over" "$OUT" "taking it over" || bad "two-tree stale lock blocked (rc $RC)"
+printf 'edited\n' >> "$T/app/mprcontents/a.mxunit"; printf 'new\n' > "$T/app/mprcontents/b.mxunit"
+printf 'unrelated staged\n' > "$T/staged.txt"; ( cd "$T" && git add staged.txt )
+OUT="$(run "$T" mdlsource/test.mdl)"; RC=$?
+[ "$RC" -ne 0 ] && has "two-tree: a dirty app/ model is refused by default" "$OUT" "app/mprcontents" || bad "two-tree: dirty model under app/ not refused"
+TH="$(git -C "$T" rev-parse HEAD)"
+OUT="$(run "$T" --commit-first mdlsource/test.mdl)"; RC=$?
+[ "$RC" -eq 0 ] && ok "two-tree: --commit-first committed and executed" || bad "two-tree --commit-first failed (rc $RC): $(printf '%s' "$OUT" | tail -4)"
+FILES="$(git -C "$T" diff --name-only "$TH" HEAD | sort | tr '\n' ' ')"
+[ "$FILES" = "app/mprcontents/a.mxunit app/mprcontents/b.mxunit " ] && ok "two-tree: commit holds exactly app/'s model paths" || bad "two-tree commit holds: $FILES"
+git -C "$T" diff --cached --name-only | grep -qx staged.txt && ok "two-tree: unrelated staged file still staged" || bad "two-tree: staged.txt lost its staged state"
+[ -e "$TLOCK" ] && bad "two-tree: lock left behind" || ok "two-tree: lock removed after the run"
+
 echo "-- watch-compat over real MDL"
 AG="$TOOLKIT/skills/agents-examples"; GAL="$TOOLKIT/examples/stylegallery/mdlsource/gallery"
 PFM="$TOOLKIT/tests/wave2/fixtures/page-fidelity-mocks"
@@ -201,6 +304,31 @@ printf "alter page Shop.Order_Overview { set Url = 'orders'; }\n" > "$WORK/url.m
 expect "$WORK/url.mdl" "restart needed" "page URL" "alter page { set Url = ... } (bug-log shape)"
 printf -- "-- create microflow Shop.ACT_X in a comment\nalter page Shop.P { set Caption = 'create microflow X; grant' on t1 }\n" > "$WORK/noise.mdl"
 expect "$WORK/noise.mdl" "watch can apply this" "" "comments and string literals never count"
+# Only ui-loop.md's watch-safe list may say "watch can apply this" (#304 review). Statements on
+# neither column are `unknown`. Real MDL where the repo has it: a shipped repro script, the
+# workflow example, a bug-log transcript, a captured DESCRIBE NAVIGATION.
+UNK="unknown — restart if behaviour looks stale"
+expect "$TOOLKIT/fixtures/import-mapping-range-repro/flip.mdl" "restart needed" "microflow" \
+  "associations + import mapping + microflow (flip.mdl) → the microflow still wins"
+grep -m1 -E '^create association RenA\.Item_Owner from RenA\.Item to RenA\.Owner;' \
+  "$TOOLKIT/bug-logs/pending-github-issues/rename-module-leaves-xpath.md" > "$WORK/assoc.mdl"
+[ -s "$WORK/assoc.mdl" ] && expect "$WORK/assoc.mdl" "$UNK" "create association" "create association (pending issue, verbatim)" \
+                         || bad "golden 'create association' line not found"
+awk '/^CREATE ENUMERATION /{p=1} p{print} p&&/^\);/{exit}' "$TOOLKIT/skills/build/workflow-example.mdl" > "$WORK/enum.mdl"
+[ -s "$WORK/enum.mdl" ] && expect "$WORK/enum.mdl" "$UNK" "CREATE ENUMERATION" "create enumeration (workflow-example.mdl)" \
+                        || bad "golden CREATE ENUMERATION block not found"
+awk '/^create java action Test\.JA_WithTypeParam/{p=1} p{print} p&&/^\$\$;/{exit}' \
+  "$TOOLKIT/bug-logs/pending-github-issues/bug87-describe-java-action-type-param-name.md" > "$WORK/ja.mdl"
+[ -s "$WORK/ja.mdl" ] && expect "$WORK/ja.mdl" "$UNK" "create java action" "create java action with a \$\$ body (bug87, verbatim)" \
+                      || bad "golden create java action block not found"
+expect "$TOOLKIT/tests/wave2/fixtures/design-audit-nav/describe-navigation-responsive.txt" "$UNK" "navigation" \
+  "create or replace navigation (captured DESCRIBE NAVIGATION output)"
+# No shipped file holds these two; written from the statement grammar in mxcli's generated
+# project CLAUDE.md (ALTER ENTITY ... MODIFY, CREATE CONSTANT) — no capture exists to take them from.
+printf 'alter entity Shop.Order modify attribute Note: String(500);\n' > "$WORK/modattr.mdl"
+expect "$WORK/modattr.mdl" "$UNK" "modify attribute" "alter entity ... modify attribute (no ADD) is not watch-safe"
+printf "create constant Shop.ApiBase type String default 'https://example.invalid';\n" > "$WORK/const.mdl"
+expect "$WORK/const.mdl" "$UNK" "create constant" "create constant"
 
 echo "-- watch-compat in a real run"
 cp "$GAL/05-demo-data.mdl" "$P/mdlsource/demo.mdl"

From 0f1c512f1f718d48fd7a37898b793e1346b3cffd Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 13 Oct 2026 15:15:20 +0000
Subject: [PATCH 2/4] docs(ui-loop): name the third watch-compat verdict
 (unknown)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The watch paragraph listed only `restart needed` and `watch can apply
this`; exec.sh now also prints `unknown — restart if behaviour looks
stale` for statements on neither column. Reworded within the same
paragraph to stay inside the baseline word budget.

Refs #287 #289

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 CHANGELOG.md      | 2 +-
 skills/ui-loop.md | 8 ++++----
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 543b3aeb..3b34b9d9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,7 +17,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are.
 
 ## Unreleased
 
-- fix(exec): **follow-ups from an independent review of #304/#306/#290: the stale-lock takeover is mutually exclusive, only watch-safe statements say "watch can apply this", `--cr` works after `--commit-first`, and the ui-only test lane names snippet/layout embedders** ([#287](https://github.com/MendixMau/mxcli-project-toolkit/issues/287), [#289](https://github.com/MendixMau/mxcli-project-toolkit/issues/289), [#274](https://github.com/MendixMau/mxcli-project-toolkit/issues/274)). (1) The takeover moved a stale lock aside and put back a fresh one with `mv -f`, which is check-then-act: with 12 contenders against one dead-pid lock, up to 3 held the lock at once. It is now serialised through an O_EXCL `.exec.lock.takeover` file (bounded by pid and age), and the lock is removed only if it still holds the stale line that was read. `tests/wave2/test-exec-lock-watch.sh` runs 10 rounds of 12 contenders and asserts at most one holder. On master 2 of 10 rounds had 2 or 3 holders; with the fix, 0. (2) `--watch-compat` said "watch can apply this" for any statement it did not classify: associations, enumerations, `ALTER ENTITY … MODIFY`, Java actions, constants and navigation. These now print `unknown — restart if behaviour looks stale`, and only statements on ui-loop.md's watch-safe list say watch can apply them. (3) The fixture now also covers a two-tree checkout (`.mpr` under `app/`) for the lock and `--commit-first`. (4) Leading flags are parsed in one loop and can come in any order. The documented `--commit-first --cr CR-07 <script>` used to commit the model and then run "--cr" as the script. A script name starting with `--` is now refused before any commit or snapshot. (5) The ui-only lane now says "journeys of every page the change reaches (embedders of a changed snippet/layout)" instead of "no other module's journeys". — MendixMau
+- fix(exec): **follow-ups from an independent review of #304/#306/#290: the stale-lock takeover is mutually exclusive, only watch-safe statements say "watch can apply this", `--cr` works after `--commit-first`, and the ui-only test lane names snippet/layout embedders** ([#287](https://github.com/MendixMau/mxcli-project-toolkit/issues/287), [#289](https://github.com/MendixMau/mxcli-project-toolkit/issues/289), [#274](https://github.com/MendixMau/mxcli-project-toolkit/issues/274)). (1) The takeover moved a stale lock aside and put back a fresh one with `mv -f`, which is check-then-act: with 12 contenders against one dead-pid lock, up to 3 held the lock at once. It is now serialised through an O_EXCL `.exec.lock.takeover` file (bounded by pid and age), and the lock is removed only if it still holds the stale line that was read. `tests/wave2/test-exec-lock-watch.sh` runs 10 rounds of 12 contenders and asserts at most one holder. On master 2 of 10 rounds had 2 or 3 holders; with the fix, 0. (2) `--watch-compat` said "watch can apply this" for any statement it did not classify: associations, enumerations, `ALTER ENTITY … MODIFY`, Java actions, constants and navigation. These now print `unknown — restart if behaviour looks stale`, and only statements on ui-loop.md's watch-safe list say watch can apply them. ui-loop.md now lists the third verdict. (3) The fixture now also covers a two-tree checkout (`.mpr` under `app/`) for the lock and `--commit-first`. (4) Leading flags are parsed in one loop and can come in any order. The documented `--commit-first --cr CR-07 <script>` used to commit the model and then run "--cr" as the script. A script name starting with `--` is now refused before any commit or snapshot. (5) The ui-only lane now says "journeys of every page the change reaches (embedders of a changed snippet/layout)" instead of "no other module's journeys". — MendixMau
 - learn(testing-shape, test-result-audit): **three test-strength rules, each with a denominator: refusals probed on the server, every undeclared 4xx a failure, one clean-database final run** ([#172](https://github.com/MendixMau/mxcli-project-toolkit/issues/172)). A field comparison of two builds against one frozen spec found the toolkit build checked permission refusals only in the client (a hidden menu item), logged unexpected 400/422 responses as information, and reached 20/20 by stitching three runs. `testing-shape.md` §7 gains three report lines (`N of N restricted pairs probed server-side`, `undeclared 4xx/5xx: 0 of M requests — each fails its step`, `one clean-DB run <id>: N of N scenarios incl. timers, not stitched`); `test-result-audit.md` gains check 2e, which carries the reasons and the field evidence and asks for those numbers. Both baseline skills stay inside the 80,000-word baseline budget (79,997): the reasons live in the on-demand audit skill, and two redundant sentences in `testing-shape.md` §4's verdict paragraphs were folded (the empty-set corollary is stated in the Trace row, `harness-architecture.md` and `report-schema.md`). The backing inbox note is trimmed to its unpromoted "Keep" items. — MendixMau
 - learn(learned-detection-gaps, module-review): **two UI defects every model gate passes: a lazy-loaded combo box filter hides its preset, and a theme that pins row heights by position lets the next row cover an inserted widget** ([#299](https://github.com/MendixMau/mxcli-project-toolkit/issues/299)). Both passed check, mxbuild, lint and the scripted checks on a 127-module production app and were found only in the running app. Two register rows with the first oracle and the pre-build check (pluggable properties that change *when* data loads; grep the theme for fixed `height` on positional row classes before an insert), and two LOOK lines in `module-review.md` §4c with denominators (`N of N filters show their preset on first load`, `N of N widgets inserted into an existing container fully visible`). — jopterhorst
 - fix(app-restart, test-stack-up): **a port held by another process before `run --local` is named and reported as "instrument blocked" (exit 4), never killed** ([#262](https://github.com/MendixMau/mxcli-project-toolkit/issues/262)). Studio Pro had started its own runtime on the app/admin ports a restart needed; `mxcli run --local` then failed with "Authentication failed" (the admin API answering was Studio Pro's), the next journey ran against Studio Pro's runtime, and four more runs were NOT RUN. `app-restart.sh` now checks the app port and the admin port (record's `adminPort`, else app + 10) before stopping anything — a holder outside the recorded process tree exits 4 with its name, pid and parent — and again after the stop, where anything still holding a port is by definition not ours. `test-stack-up.sh` runs the same check wherever it would tell you to start `run --local` (`--no-docker`, no Docker daemon, `--check` with a leftover record), on the record's ports, `RUN_LOCAL_APP_PORT`/`RUN_LOCAL_ADMIN_PORT`, or mxcli's defaults 8080/8090. Holder lookup: lsof, then ss, then netstat + tasklist on Windows; unnamed holders still block when nothing of ours is running. Fixtures: `test-app-restart.sh` +2 cases (14 assertions, all fail on the old script), `test-stack-up-local.sh` T7 (4 of 6 fail on the old script). — AlvinnYeo
diff --git a/skills/ui-loop.md b/skills/ui-loop.md
index 9c89980d..50139995 100644
--- a/skills/ui-loop.md
+++ b/skills/ui-loop.md
@@ -205,10 +205,10 @@ diagnosis rounds spent on "defects" that were a stale runtime (#284, #275, #285)
 | | a new page (`create page`), or a page that gets a `Url` — the route table predates it and the deep link lands on Home |
 | | theme SCSS or theme JS (`themesource/`, `theme/`) — one edit dropped the page bundles (404), another left a 24 px column the model says is 120 |
 
-`bin/exec.sh` runs this table for you after every applied script (`--watch-compat <script>`
-prints the same verdict without running anything): it reads the statement heads and checks theme
-SCSS/JS against the running app's boot time, and prints `restart needed: <reasons>` or `watch can
-apply this`. Advisory only — it never blocks. A `create or replace page` is reported reloadable
+`bin/exec.sh` runs this table after every applied script (`--watch-compat <script>` alone
+writes nothing): it reads statement heads, checks theme SCSS/JS against the app's boot time, and
+prints `restart needed: <reasons>`, `watch can apply this`, or, for a statement in neither
+column, `unknown — restart if behaviour looks stale`. Advisory only — it never blocks. A `create or replace page` is reported reloadable
 with a note: restart if that page is new, because a script cannot tell new from replaced.
 
 **A stale runtime looks like a defect.** Before diagnosing any of these right after an exec,

From 79de40489a69a5fe68d9ad9d367838bd62bbd952 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 13 Oct 2026 15:47:30 +0000
Subject: [PATCH 3/4] fix(exec): fresh empty takeover file is not stale (-mmin
 +1); align with test-scratch

Review of #324: `find -mmin +0` matched a takeover file created a second
ago, so a live contender's fresh empty file was moved aside and a third
contender got in (reviewer: 2-3 holders in 6/15 and 16/30 rounds with a
100 ms delay). Now -mmin +1; a moved-aside copy is deleted only if it is
what was judged stale, else restored with ln (left on disk if ln fails);
the holder removes the takeover file only while it holds its own line.
Body identical to test-scratch.sh take_over() in #322. Reviewer's delayed
harness against this body: 0/15 rounds with >1 holder.

Also: microflow-body verbs, CREATE FOLDER and MOVE ... TO FOLDER are
neutral for the watch verdict; agent-roles.md names the unknown verdict.

Refs #287 #289

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 CHANGELOG.md                        |  2 +-
 project-bin/exec.sh                 | 29 ++++++++++++++++++++---------
 skills/agent-roles.md               | 12 ++++++------
 tests/wave2/test-exec-lock-watch.sh | 17 +++++++++++++++++
 4 files changed, 44 insertions(+), 16 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3b34b9d9..8af21e83 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,7 +17,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are.
 
 ## Unreleased
 
-- fix(exec): **follow-ups from an independent review of #304/#306/#290: the stale-lock takeover is mutually exclusive, only watch-safe statements say "watch can apply this", `--cr` works after `--commit-first`, and the ui-only test lane names snippet/layout embedders** ([#287](https://github.com/MendixMau/mxcli-project-toolkit/issues/287), [#289](https://github.com/MendixMau/mxcli-project-toolkit/issues/289), [#274](https://github.com/MendixMau/mxcli-project-toolkit/issues/274)). (1) The takeover moved a stale lock aside and put back a fresh one with `mv -f`, which is check-then-act: with 12 contenders against one dead-pid lock, up to 3 held the lock at once. It is now serialised through an O_EXCL `.exec.lock.takeover` file (bounded by pid and age), and the lock is removed only if it still holds the stale line that was read. `tests/wave2/test-exec-lock-watch.sh` runs 10 rounds of 12 contenders and asserts at most one holder. On master 2 of 10 rounds had 2 or 3 holders; with the fix, 0. (2) `--watch-compat` said "watch can apply this" for any statement it did not classify: associations, enumerations, `ALTER ENTITY … MODIFY`, Java actions, constants and navigation. These now print `unknown — restart if behaviour looks stale`, and only statements on ui-loop.md's watch-safe list say watch can apply them. ui-loop.md now lists the third verdict. (3) The fixture now also covers a two-tree checkout (`.mpr` under `app/`) for the lock and `--commit-first`. (4) Leading flags are parsed in one loop and can come in any order. The documented `--commit-first --cr CR-07 <script>` used to commit the model and then run "--cr" as the script. A script name starting with `--` is now refused before any commit or snapshot. (5) The ui-only lane now says "journeys of every page the change reaches (embedders of a changed snippet/layout)" instead of "no other module's journeys". — MendixMau
+- fix(exec): **follow-ups from an independent review of #304/#306/#290: the stale-lock takeover is mutually exclusive, only watch-safe statements say "watch can apply this", `--cr` works after `--commit-first`, and the ui-only test lane names snippet/layout embedders** ([#287](https://github.com/MendixMau/mxcli-project-toolkit/issues/287), [#289](https://github.com/MendixMau/mxcli-project-toolkit/issues/289), [#274](https://github.com/MendixMau/mxcli-project-toolkit/issues/274)). (1) The takeover moved a stale lock aside and put back a fresh one with `mv -f`, which is check-then-act: with 12 contenders against one dead-pid lock, up to 3 held the lock at once. It is now serialised through an O_EXCL `.exec.lock.takeover` file (bounded by pid and age), and the lock is removed only if it still holds the stale line that was read. `tests/wave2/test-exec-lock-watch.sh` runs 10 rounds of 12 contenders and asserts at most one holder. On master 2 of 10 rounds had 2 or 3 holders; with the fix, 0. (2) `--watch-compat` said "watch can apply this" for any statement it did not classify: associations, enumerations, `ALTER ENTITY … MODIFY`, Java actions, constants and navigation. These now print `unknown — restart if behaviour looks stale`, and only statements on ui-loop.md's watch-safe list say watch can apply them. ui-loop.md now lists the third verdict. A review of this PR found that an empty takeover file was judged stale by `find -mmin +0` within a second of its creation, so a live contender's fresh file could be moved aside and a third contender could get in. The threshold is now `-mmin +1`, the holder removes the takeover file only while it still holds its own line, and a fixture case checks that a fresh empty takeover file is respected. Microflow-body verbs, `CREATE FOLDER` and moves into a folder are neutral for the watch verdict. agent-roles.md names the `unknown` verdict. (3) The fixture now also covers a two-tree checkout (`.mpr` under `app/`) for the lock and `--commit-first`. (4) Leading flags are parsed in one loop and can come in any order. The documented `--commit-first --cr CR-07 <script>` used to commit the model and then run "--cr" as the script. A script name starting with `--` is now refused before any commit or snapshot. (5) The ui-only lane now says "journeys of every page the change reaches (embedders of a changed snippet/layout)" instead of "no other module's journeys". — MendixMau
 - learn(testing-shape, test-result-audit): **three test-strength rules, each with a denominator: refusals probed on the server, every undeclared 4xx a failure, one clean-database final run** ([#172](https://github.com/MendixMau/mxcli-project-toolkit/issues/172)). A field comparison of two builds against one frozen spec found the toolkit build checked permission refusals only in the client (a hidden menu item), logged unexpected 400/422 responses as information, and reached 20/20 by stitching three runs. `testing-shape.md` §7 gains three report lines (`N of N restricted pairs probed server-side`, `undeclared 4xx/5xx: 0 of M requests — each fails its step`, `one clean-DB run <id>: N of N scenarios incl. timers, not stitched`); `test-result-audit.md` gains check 2e, which carries the reasons and the field evidence and asks for those numbers. Both baseline skills stay inside the 80,000-word baseline budget (79,997): the reasons live in the on-demand audit skill, and two redundant sentences in `testing-shape.md` §4's verdict paragraphs were folded (the empty-set corollary is stated in the Trace row, `harness-architecture.md` and `report-schema.md`). The backing inbox note is trimmed to its unpromoted "Keep" items. — MendixMau
 - learn(learned-detection-gaps, module-review): **two UI defects every model gate passes: a lazy-loaded combo box filter hides its preset, and a theme that pins row heights by position lets the next row cover an inserted widget** ([#299](https://github.com/MendixMau/mxcli-project-toolkit/issues/299)). Both passed check, mxbuild, lint and the scripted checks on a 127-module production app and were found only in the running app. Two register rows with the first oracle and the pre-build check (pluggable properties that change *when* data loads; grep the theme for fixed `height` on positional row classes before an insert), and two LOOK lines in `module-review.md` §4c with denominators (`N of N filters show their preset on first load`, `N of N widgets inserted into an existing container fully visible`). — jopterhorst
 - fix(app-restart, test-stack-up): **a port held by another process before `run --local` is named and reported as "instrument blocked" (exit 4), never killed** ([#262](https://github.com/MendixMau/mxcli-project-toolkit/issues/262)). Studio Pro had started its own runtime on the app/admin ports a restart needed; `mxcli run --local` then failed with "Authentication failed" (the admin API answering was Studio Pro's), the next journey ran against Studio Pro's runtime, and four more runs were NOT RUN. `app-restart.sh` now checks the app port and the admin port (record's `adminPort`, else app + 10) before stopping anything — a holder outside the recorded process tree exits 4 with its name, pid and parent — and again after the stop, where anything still holding a port is by definition not ours. `test-stack-up.sh` runs the same check wherever it would tell you to start `run --local` (`--no-docker`, no Docker daemon, `--check` with a leftover record), on the record's ports, `RUN_LOCAL_APP_PORT`/`RUN_LOCAL_ADMIN_PORT`, or mxcli's defaults 8080/8090. Holder lookup: lsof, then ss, then netstat + tasklist on Windows; unnamed holders still block when nothing of ours is running. Fixtures: `test-app-restart.sh` +2 cases (14 assertions, all fail on the old script), `test-stack-up-local.sh` T7 (4 of 6 fail on the old script). — AlvinnYeo
diff --git a/project-bin/exec.sh b/project-bin/exec.sh
index 9fbe82ff..48802384 100755
--- a/project-bin/exec.sh
+++ b/project-bin/exec.sh
@@ -282,6 +282,11 @@ mxtk_watch_compat() {  # $1 = MDL script; prints "restart\t<reasons>" | "unknown
           # not on either column is UNKNOWN, never "watch can apply this".
           else if ((v == "ALTER" && (o1 == "PAGE" || o1 == "SNIPPET")) || (v == "CREATE" && o1 == "SNIPPET"))
             ;
+          # Neutral: microflow-body activities (their CREATE MICROFLOW head already decides),
+          # a folder, a move into a folder.
+          else if (v ~ /^(DECLARE|CHANGE|RETRIEVE|COMMIT|CALL)$/ || (v == "CREATE" && o1 == "FOLDER") \
+                   || (v == "MOVE" && toupper(t) ~ /[ \t]TO[ \t]+FOLDER([ \t]|$)/))
+            ;
           else if (nunk < 3) {
             h = t; if (length(h) > 50) h = substr(h, 1, 50) "..."
             unk = unk (nunk++ ? "; " : "") "line " NR ": " h
@@ -536,30 +541,36 @@ exec_lock_release() {  # the trap: remove the lock only while it is still ours
 # moved A's fresh lock aside, C's noclobber write landed in the gap, B saw a lock and deleted
 # A's: 12 contenders gave up to 3 holders at once (tests/wave2/test-exec-lock-watch.sh).
 # A takeover file left by a holder killed inside those few microseconds is stale once its pid is
-# dead or it is older than 10 s (an EMPTY one once it is a minute old); it is moved aside, and put back with `ln` (fails if a new one
-# exists — never clobbers) if what was moved is not the one judged stale.
+# dead or it is older than 10 s (an EMPTY one once it is over a minute old — `find -mmin +1`;
+# `+0` matched a file created a second ago, so a live contender's fresh takeover file was judged
+# stale and a third contender got in: review of #324). It is moved aside, and put back with `ln`
+# (never clobbers; left on disk if that fails) if what was moved is not the one judged stale.
+# The holder removes the takeover file only while it still holds the line it wrote.
 exec_lock_takeover() {  # $1 = the stale lock line; 0 iff it was removed (or already gone)
-  _tk="$LOCK.takeover"
-  if ! ( set -o noclobber; printf '%s %s\n' "$$" "$(date +%s)" > "$_tk" ) 2>/dev/null; then
+  _tk="$LOCK.takeover"; _mine="$$ $(date +%s)"
+  if ! ( set -o noclobber; printf '%s\n' "$_mine" > "$_tk" ) 2>/dev/null; then
     _t="$(head -1 "$_tk" 2>/dev/null || true)"; _tpid="${_t%% *}"; _tsince="${_t#* }"
     case "$_tsince" in ''|*[!0-9]*) _tsince=0 ;; esac
     _tstale=0
     if [ -n "$_t" ]; then
       { ! kill -0 "$_tpid" 2>/dev/null || [ $(( $(date +%s) - _tsince )) -gt 10 ]; } && _tstale=1
-    elif [ -n "$(find "$_tk" -mmin +0 2>/dev/null)" ]; then
-      _tstale=1   # empty for a minute: its creator died between the create and the write
+    elif [ -n "$(find "$_tk" -mmin +1 2>/dev/null)" ]; then
+      _tstale=1   # empty for over a minute: its creator died between the create and the write
     fi
     if [ "$_tstale" = 1 ]; then
       if mv "$_tk" "$_tk.stale.$$" 2>/dev/null; then
-        [ "$(head -1 "$_tk.stale.$$" 2>/dev/null || true)" = "$_t" ] || ln "$_tk.stale.$$" "$_tk" 2>/dev/null || true
-        rm -f "$_tk.stale.$$"
+        # Remove what was moved ONLY if it is what was judged stale; anything else is someone's
+        # live takeover file: put it back (ln never clobbers), and if that fails leave it be.
+        # Same body as test-scratch.sh's take_over() — keep the two in step (PR #322).
+        if [ "$(head -1 "$_tk.stale.$$" 2>/dev/null || true)" = "$_t" ]; then rm -f "$_tk.stale.$$"
+        else ln "$_tk.stale.$$" "$_tk" 2>/dev/null && rm -f "$_tk.stale.$$"; fi
       fi
     fi
     return 1
   fi
   _now="$(head -1 "$LOCK" 2>/dev/null || true)"
   [ "$_now" = "$1" ] && rm -f "$LOCK"
-  rm -f "$_tk"
+  [ "$(head -1 "$_tk" 2>/dev/null || true)" = "$_mine" ] && rm -f "$_tk"   # only our own takeover file
   return 0
 }
 LOCK_TAKEN=0
diff --git a/skills/agent-roles.md b/skills/agent-roles.md
index 01ba7ba4..938b8e5b 100644
--- a/skills/agent-roles.md
+++ b/skills/agent-roles.md
@@ -76,12 +76,12 @@ shows up in the bill:
    message to an agent that has already reported — that restarts it at its full context.
 
 **App restarts: the implementer restarts its own app, through one script only.** Write this into
-every implementer brief: "When `exec.sh` prints `restart needed`, run `./bin/app-restart.sh`
-yourself and carry on; never stop or start an app any other way (no kill by name, no `pkill`, no
-second `run --local`), and never touch another lane's app." The helper stops only the pid that
-`run --local` recorded for that project and refuses otherwise (`ui-loop.md` § "What watch picks
-up"). The old rule, that only the lead restarts apps, came from a broad kill in one lane that took
-down another lane's app; the helper cannot do that, and the rule cost 24 implementer
+every implementer brief: "When `exec.sh` prints `restart needed`, or `unknown — restart if
+behaviour looks stale` and it does, run `./bin/app-restart.sh` yourself and carry on; never
+stop or start an app another way (no `pkill`, no second `run --local`) or touch another lane's
+app." The helper stops only the pid that `run --local` recorded for that project and refuses
+otherwise (`ui-loop.md` § "What watch picks up"). The old lead-only rule came from a broad kill
+in one lane that took down another lane's app; the helper cannot do that, and the rule cost 24 implementer
 restart-resumes (41.6M tokens, 8.5% of subagent tokens) in the 2026-10-12 run (#289). If the
 helper refuses (exit 3) or the app does not come back (exit 1), the implementer reports
 `BLOCKED NEEDS_RESTART` with its output, as before.
diff --git a/tests/wave2/test-exec-lock-watch.sh b/tests/wave2/test-exec-lock-watch.sh
index 29c8c6c5..04f238eb 100755
--- a/tests/wave2/test-exec-lock-watch.sh
+++ b/tests/wave2/test-exec-lock-watch.sh
@@ -157,6 +157,17 @@ printf '%s 1700000000 old.mdl\n' "$(dead_pid)" > "$LOCK"
 OUT="$(run "$P" mdlsource/test.mdl)"; RC=$?
 [ "$RC" -eq 0 ] && ok "an empty takeover file older than a minute is stale too" || bad "empty old takeover file blocked (rc $RC)"
 rm -f "$LOCK.takeover"
+# A FRESH empty takeover file is a live contender between its create and its write, NOT stale.
+# `find -mmin +0` judged it stale within a second, so a third contender got in (review of #324).
+printf '%s 1700000000 old.mdl\n' "$(dead_pid)" > "$LOCK"
+: > "$LOCK.takeover"
+OUT="$(run "$P" mdlsource/test.mdl)"; RC=$?
+[ "$RC" -ne 0 ] && ok "a fresh empty takeover file is respected: the run waits, then refuses (rc $RC)" \
+  || bad "a fresh empty takeover file was judged stale and the run went ahead"
+hasnt "  and it did not execute" "$OUT" "fake mxcli exec"
+[ -e "$LOCK.takeover" ] && [ ! -s "$LOCK.takeover" ] && ok "  and the contender's takeover file was left in place" \
+  || bad "the fresh takeover file was moved or replaced"
+rm -f "$LOCK" "$LOCK.takeover"
 
 echo "-- lock: old bare-pid format, dead pid"
 dead_pid > "$LOCK"
@@ -329,6 +340,12 @@ printf 'alter entity Shop.Order modify attribute Note: String(500);\n' > "$WORK/
 expect "$WORK/modattr.mdl" "$UNK" "modify attribute" "alter entity ... modify attribute (no ADD) is not watch-safe"
 printf "create constant Shop.ApiBase type String default 'https://example.invalid';\n" > "$WORK/const.mdl"
 expect "$WORK/const.mdl" "$UNK" "create constant" "create constant"
+# Neutral for the watch verdict: a move into a folder (verbatim from a pending issue) next to a
+# watch-safe page edit stays "watch can apply this".
+{ grep -m1 -E "^move page RenA\.Other to folder 'Pages/Same';" \
+    "$TOOLKIT/bug-logs/pending-github-issues/rename-page-renames-folder.md"; cat "$PFM/bind-contract-alter.mdl"; } > "$WORK/movefolder.mdl"
+grep -q '^move page' "$WORK/movefolder.mdl" && expect "$WORK/movefolder.mdl" "watch can apply this" "" "move page ... to folder + alter page is not 'unknown'" \
+  || bad "golden 'move page ... to folder' line not found"
 
 echo "-- watch-compat in a real run"
 cp "$GAL/05-demo-data.mdl" "$P/mdlsource/demo.mdl"

From 90a69574c29774cf060664da132fd1f7b509470e Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 13 Oct 2026 16:01:27 +0000
Subject: [PATCH 4/4] fix(exec): show lint-gate's SEC014 note on a clean run

PR #312 makes lint-gate.sh print a non-blocking `note: SEC014 not
configured` on stderr. run_lint_gate captured that output and showed it
only on failure, so the note never appeared on a clean exec. Always echo
that one line; exit code unchanged. Fixture: stub lint-gate with the
note on stderr and rc 0 -> exec output shows it (fails on the prior head).

Refs #287

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 CHANGELOG.md                        |  2 +-
 project-bin/exec.sh                 |  3 +++
 tests/wave2/test-exec-lock-watch.sh | 15 +++++++++++++++
 3 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8af21e83..c3b3a66d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,7 +17,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are.
 
 ## Unreleased
 
-- fix(exec): **follow-ups from an independent review of #304/#306/#290: the stale-lock takeover is mutually exclusive, only watch-safe statements say "watch can apply this", `--cr` works after `--commit-first`, and the ui-only test lane names snippet/layout embedders** ([#287](https://github.com/MendixMau/mxcli-project-toolkit/issues/287), [#289](https://github.com/MendixMau/mxcli-project-toolkit/issues/289), [#274](https://github.com/MendixMau/mxcli-project-toolkit/issues/274)). (1) The takeover moved a stale lock aside and put back a fresh one with `mv -f`, which is check-then-act: with 12 contenders against one dead-pid lock, up to 3 held the lock at once. It is now serialised through an O_EXCL `.exec.lock.takeover` file (bounded by pid and age), and the lock is removed only if it still holds the stale line that was read. `tests/wave2/test-exec-lock-watch.sh` runs 10 rounds of 12 contenders and asserts at most one holder. On master 2 of 10 rounds had 2 or 3 holders; with the fix, 0. (2) `--watch-compat` said "watch can apply this" for any statement it did not classify: associations, enumerations, `ALTER ENTITY … MODIFY`, Java actions, constants and navigation. These now print `unknown — restart if behaviour looks stale`, and only statements on ui-loop.md's watch-safe list say watch can apply them. ui-loop.md now lists the third verdict. A review of this PR found that an empty takeover file was judged stale by `find -mmin +0` within a second of its creation, so a live contender's fresh file could be moved aside and a third contender could get in. The threshold is now `-mmin +1`, the holder removes the takeover file only while it still holds its own line, and a fixture case checks that a fresh empty takeover file is respected. Microflow-body verbs, `CREATE FOLDER` and moves into a folder are neutral for the watch verdict. agent-roles.md names the `unknown` verdict. (3) The fixture now also covers a two-tree checkout (`.mpr` under `app/`) for the lock and `--commit-first`. (4) Leading flags are parsed in one loop and can come in any order. The documented `--commit-first --cr CR-07 <script>` used to commit the model and then run "--cr" as the script. A script name starting with `--` is now refused before any commit or snapshot. (5) The ui-only lane now says "journeys of every page the change reaches (embedders of a changed snippet/layout)" instead of "no other module's journeys". — MendixMau
+- fix(exec): **follow-ups from an independent review of #304/#306/#290: the stale-lock takeover is mutually exclusive, only watch-safe statements say "watch can apply this", `--cr` works after `--commit-first`, and the ui-only test lane names snippet/layout embedders** ([#287](https://github.com/MendixMau/mxcli-project-toolkit/issues/287), [#289](https://github.com/MendixMau/mxcli-project-toolkit/issues/289), [#274](https://github.com/MendixMau/mxcli-project-toolkit/issues/274)). (1) The takeover moved a stale lock aside and put back a fresh one with `mv -f`, which is check-then-act: with 12 contenders against one dead-pid lock, up to 3 held the lock at once. It is now serialised through an O_EXCL `.exec.lock.takeover` file (bounded by pid and age), and the lock is removed only if it still holds the stale line that was read. `tests/wave2/test-exec-lock-watch.sh` runs 10 rounds of 12 contenders and asserts at most one holder. On master 2 of 10 rounds had 2 or 3 holders; with the fix, 0. (2) `--watch-compat` said "watch can apply this" for any statement it did not classify: associations, enumerations, `ALTER ENTITY … MODIFY`, Java actions, constants and navigation. These now print `unknown — restart if behaviour looks stale`, and only statements on ui-loop.md's watch-safe list say watch can apply them. ui-loop.md now lists the third verdict. A review of this PR found that an empty takeover file was judged stale by `find -mmin +0` within a second of its creation, so a live contender's fresh file could be moved aside and a third contender could get in. The threshold is now `-mmin +1`, the holder removes the takeover file only while it still holds its own line, and a fixture case checks that a fresh empty takeover file is respected. Microflow-body verbs, `CREATE FOLDER` and moves into a folder are neutral for the watch verdict. agent-roles.md names the `unknown` verdict. A clean exec now also shows lint-gate's non-blocking `note: SEC014 not configured` line (#312), which was only visible on a failing lint run; the exit code is unchanged. (3) The fixture now also covers a two-tree checkout (`.mpr` under `app/`) for the lock and `--commit-first`. (4) Leading flags are parsed in one loop and can come in any order. The documented `--commit-first --cr CR-07 <script>` used to commit the model and then run "--cr" as the script. A script name starting with `--` is now refused before any commit or snapshot. (5) The ui-only lane now says "journeys of every page the change reaches (embedders of a changed snippet/layout)" instead of "no other module's journeys". — MendixMau
 - learn(testing-shape, test-result-audit): **three test-strength rules, each with a denominator: refusals probed on the server, every undeclared 4xx a failure, one clean-database final run** ([#172](https://github.com/MendixMau/mxcli-project-toolkit/issues/172)). A field comparison of two builds against one frozen spec found the toolkit build checked permission refusals only in the client (a hidden menu item), logged unexpected 400/422 responses as information, and reached 20/20 by stitching three runs. `testing-shape.md` §7 gains three report lines (`N of N restricted pairs probed server-side`, `undeclared 4xx/5xx: 0 of M requests — each fails its step`, `one clean-DB run <id>: N of N scenarios incl. timers, not stitched`); `test-result-audit.md` gains check 2e, which carries the reasons and the field evidence and asks for those numbers. Both baseline skills stay inside the 80,000-word baseline budget (79,997): the reasons live in the on-demand audit skill, and two redundant sentences in `testing-shape.md` §4's verdict paragraphs were folded (the empty-set corollary is stated in the Trace row, `harness-architecture.md` and `report-schema.md`). The backing inbox note is trimmed to its unpromoted "Keep" items. — MendixMau
 - learn(learned-detection-gaps, module-review): **two UI defects every model gate passes: a lazy-loaded combo box filter hides its preset, and a theme that pins row heights by position lets the next row cover an inserted widget** ([#299](https://github.com/MendixMau/mxcli-project-toolkit/issues/299)). Both passed check, mxbuild, lint and the scripted checks on a 127-module production app and were found only in the running app. Two register rows with the first oracle and the pre-build check (pluggable properties that change *when* data loads; grep the theme for fixed `height` on positional row classes before an insert), and two LOOK lines in `module-review.md` §4c with denominators (`N of N filters show their preset on first load`, `N of N widgets inserted into an existing container fully visible`). — jopterhorst
 - fix(app-restart, test-stack-up): **a port held by another process before `run --local` is named and reported as "instrument blocked" (exit 4), never killed** ([#262](https://github.com/MendixMau/mxcli-project-toolkit/issues/262)). Studio Pro had started its own runtime on the app/admin ports a restart needed; `mxcli run --local` then failed with "Authentication failed" (the admin API answering was Studio Pro's), the next journey ran against Studio Pro's runtime, and four more runs were NOT RUN. `app-restart.sh` now checks the app port and the admin port (record's `adminPort`, else app + 10) before stopping anything — a holder outside the recorded process tree exits 4 with its name, pid and parent — and again after the stop, where anything still holding a port is by definition not ours. `test-stack-up.sh` runs the same check wherever it would tell you to start `run --local` (`--no-docker`, no Docker daemon, `--check` with a leftover record), on the record's ports, `RUN_LOCAL_APP_PORT`/`RUN_LOCAL_ADMIN_PORT`, or mxcli's defaults 8080/8090. Holder lookup: lsof, then ss, then netstat + tasklist on Windows; unnamed holders still block when nothing of ours is running. Fixtures: `test-app-restart.sh` +2 cases (14 assertions, all fail on the old script), `test-stack-up-local.sh` T7 (4 of 6 fail on the old script). — AlvinnYeo
diff --git a/project-bin/exec.sh b/project-bin/exec.sh
index 48802384..3e602957 100755
--- a/project-bin/exec.sh
+++ b/project-bin/exec.sh
@@ -824,6 +824,9 @@ run_lint_gate() {
   # row at all (measured on the first wired run in a real project, 2026-09-24). Capture explicitly.
   LINT_RC=0
   bash "$PROJECT_ROOT/bin/lint-gate.sh" >"$_lo" 2>&1 || LINT_RC=$?
+  # lint-gate's non-blocking SEC014 note (#312: rule installed, decision not made) is otherwise
+  # visible only on a failing run, because the capture above is shown only then. Always echo it.
+  [ -f "$_lo" ] && { grep '^note: SEC014' "$_lo" 2>/dev/null | sed 's/^/    /' || true; }
   case "$LINT_RC" in
     0) LINT_DETAIL="lint unchanged vs baseline"; echo "  ✓ lint: no rule rose vs baseline" ;;
     1) # Rule ids are matched as [A-Z][A-Z0-9-]*[0-9]+, not [A-Z]+[0-9]+: mxcli's built-in
diff --git a/tests/wave2/test-exec-lock-watch.sh b/tests/wave2/test-exec-lock-watch.sh
index 04f238eb..0ceb6a7c 100755
--- a/tests/wave2/test-exec-lock-watch.sh
+++ b/tests/wave2/test-exec-lock-watch.sh
@@ -369,6 +369,21 @@ touch "$P/.mxcli/run-local.json"
 OUT="$(run "$P" mdlsource/page.mdl)"
 has "same script, SCSS older than the boot → watch applies it" "$OUT" "→ Watch: watch can apply this"
 
+echo "-- lint-gate's SEC014 note reaches a clean exec (#312)"
+# The note line is lint-gate.sh's own text in PR #312 (project-bin/lint-gate.sh, stderr, rc 0).
+cat > "$P/bin/lint-gate.sh" <<'LG'
+#!/usr/bin/env bash
+echo "note: SEC014 not configured — set .claude/lint-config.yaml rules: SEC014: options: external_roles (ask the user; 'none' is their decision)" >&2
+echo "PASS: no rule rose vs baseline"
+exit 0
+LG
+chmod +x "$P/bin/lint-gate.sh"
+OUT="$(run "$P" mdlsource/test.mdl)"; RC=$?
+[ "$RC" -eq 0 ] && ok "clean lint run still exits 0" || bad "lint note changed the exit code (rc $RC)"
+has "the SEC014 note is shown on a clean run" "$OUT" "    note: SEC014 not configured"
+has "  and the run still reports lint clean" "$OUT" "lint: no rule rose"
+rm -f "$P/bin/lint-gate.sh"
+
 echo ""
 echo "PASS=$PASS FAIL=$FAIL"
 [ "$FAIL" -eq 0 ]