From d2edf0b0ebf9cbb58254119265744779a9962a41 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 14 Oct 2026 15:50:05 +0000
Subject: [PATCH 1/7] =?UTF-8?q?feat(exec):=20opt-in=20--on-copy=20?=
 =?UTF-8?q?=E2=80=94=20exec=20and=20gate=20on=20a=20scratch=20copy,=20prom?=
 =?UTF-8?q?ote=20by=20rename=20(#350)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

EXEC_ON_COPY=1 or --on-copy runs mxcli exec and the mxbuild gate on a copy of the
model tree under the existing exec lock, and writes the live model only by a
rename-based promotion after a verified pass. Promotion refuses while Studio Pro
holds the model, when the live model changed since the copy, or across
filesystems; a part-way swap renames back or restores the snapshot. Any other
outcome leaves the live model untouched and keeps the copy with a resume hint.
The default path is unchanged. Copy routine shared with test-scratch.sh via
_common.sh (mxtk_copy_model_tree).

Fixture tests/wave2/test-exec-on-copy.sh (108 checks, both layouts) and bench
tests/wave2/bench-exec-on-copy.sh. Field evidence: none (stub-only).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 CHANGELOG.md                      |   1 +
 project-bin/_common.sh            |  12 ++
 project-bin/exec.sh               | 310 ++++++++++++++++++++++++++++--
 project-bin/test-scratch.sh       |   3 +-
 skills/iterative-build-loop.md    |   2 +
 tests/wave2/bench-exec-on-copy.sh | 179 +++++++++++++++++
 tests/wave2/test-exec-on-copy.sh  | 236 +++++++++++++++++++++++
 7 files changed, 722 insertions(+), 21 deletions(-)
 create mode 100755 tests/wave2/bench-exec-on-copy.sh
 create mode 100755 tests/wave2/test-exec-on-copy.sh

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ff60ea83..d1f31fb9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,6 +19,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are. Named m
 
 ## Unreleased
 
+- new(exec): **`exec.sh --on-copy` (or `EXEC_ON_COPY=1`), opt-in: the script and the mxbuild gate run on a scratch copy, and the live model is written only by a rename-based promotion after a verified pass** ([#350](https://github.com/MendixMau/mxcli-project-toolkit/issues/350)). By default the live model holds an unverified write for the length of the gate (22-65 s per apply in the field), and keeps it when exec.sh is killed. Promotion is refused while Studio Pro holds the model (even under `FORCE_EXEC`), when the live model changed since the copy (cksum manifest), or when the copy is on another filesystem. A swap that fails part-way renames back, else restores the snapshot. On any other outcome the live model is untouched and the copy is kept under `.mpr-snapshots/.on-copy/` with a resume hint (newest 3 kept). Files exec writes outside the model (javasource/) are promoted with it. The default path is unchanged. The copy routine moved from `test-scratch.sh` into `_common.sh` (`mxtk_copy_model_tree`). Fixture `tests/wave2/test-exec-on-copy.sh` (108 checks, both layouts; 71 fail on master). Bench `tests/wave2/bench-exec-on-copy.sh` (stub mxbuild 2 s, an input): with exec.sh killed mid-gate the live model stayed byte-identical in 0/10 default runs and 10/10 on-copy runs at 500, 5,000 and 20,000 units. The broken window fell from about 2.1 s (clean) and 5.5-25.4 s (failed gate) to a 15-42 ms swap, at a cost of +1.4 s, +3.7 s and +10.9 s wall time per exec. Field evidence: none yet (stub-only); a field run with Studio Pro closed and then open is owed before it can become the default. Statement-level resume from the kept copy is a follow-up. — external review (#350), MendixMau
 - process(build): **Stage 5 drafts the ready set in parallel and applies serially.** The runbook dispatch row said "sequential within a module", which serialised drafting even for independent scripts; it now points to `iterative-build-loop.md` → Gate cost, the single statement of the rule. The unit is the build-plan row: every `BUILD` row whose "Depends on" rows are all applied, minus overlapping writers (two rows that replace, alter or drop+create the same document never share a ready set, and no row is drafted while it overlaps a queued unapplied one; `brd-to-build-plan.md` has Produces name every document a row writes), runs at once, its scripts in order, one `mdl-agent` per script. Applies stay one at a time through `bin/exec.sh`, and the ready set is recomputed after each. A queued draft made before a sibling apply landed is re-checked with `mxcli diff --format struct` (preflight STOP rule 23); any removal line (checked against `describe` per BUG-146) or STOP rule 21 target means re-draft, never patch, because a stale restatement of a shared document is exactly rule 21's silent seed-call loss and passes `check --references`. Report `ready set N, drafted N, applied k`; the `mdl-agent` template says a drafter never applies and never depends on an unapplied draft. Field evidence: none yet. — MendixMau
 - fix(platform-link): **CLI commits now show their changed documents in Studio Pro History.** Studio Pro's History → Model changes pane reads a `ModelChanges` array from the commit's `refs/notes/mx_metadata` note. Trap 6c's hand-written template set it to `[]`, so every mxcli/agent commit showed "Model changes 0" (field project: 270 of 270 notes empty). New `project-bin/mx-metadata-note.py` (stdlib only) computes the array from the commit's changed `.mxunit` files, in Studio Pro's entry shape: Status, UnitID, UnitType, UnitName and Module (walked up the `.mpr` Unit tree). It has `changes` / `write` / `backfill` / `sync <remote>` subcommands. `install-project-hooks.sh` now also installs post-commit and post-rewrite hooks that write the note and never block, and `--check` covers them, so `sync-project.sh` rolls them out to wired projects. Notes are published with `mx-metadata-note.py sync <remote>` after the branch push. Push config is never touched. With mxcli v0.26+ in the project root the hooks call `mxcli git note --write` instead (mendixlabs/mxcli#1337); the Python script is the fallback for older pins, and on 160 field commits both wrote the same 3,594 entries. Trap 6c rewritten. Measured against Studio Pro's own notes, 51 commits in 5 apps: 3387/3389 entries exact on all five fields. Field run on a 357-commit Mendix 11.15.0 app: 158 notes backfilled and pushed, and Studio Pro History lists the documents per revision. Review fixes: an earlier revision added `HEAD` + the notes ref to `remote.<r>.push`. It was dropped because any push refspec replaces `push.default`. A branch tracking a differently named upstream got a new same-named branch on Team Server where `simple` refuses, a missing local notes ref failed the whole push, and nobody knows whether Studio Pro's own push reads that config. The installer now only fetches the remote's notes (non-forced). It removes that exact `HEAD` + notes pair if present, and leaves and reports any other entry. `sync` handles a remote with no notes ref (it used to exit 1) and retries a rejected push once after re-merging. A note that already lists changes (Studio Pro's) is never overwritten by `write`/`backfill` without `--force`, and `sync` keeps a colleague's non-empty note over ours. The mxcli probe greps `git note --help` for `--write`. Hooks and docs call the script through `resolve_py`. Fixture `tests/wave2/test-mx-metadata-note.sh` (40 cases, over real captured template units; single- and two-tree layouts, amend, backfill and `--force`, push exit codes identical to a no-hooks clone, leftover-refspec cleanup, sync to an empty remote and its retry, notes fetch at install, a diverged notes merge; green under `init.defaultBranch` master and main). — field project (Mendix 11.15 app), MendixMau
 - learn(fixture-seeding): **explore the data structure first, choose rows by use case, scan actions for resets before any run.** Two seeding runs on public template apps: seeding raised journey passes 33 -> 58 and 20 -> 51 of the same sets (FAIL 93 -> 68, 163 -> 132; INVALID unchanged), and a "Reset all demodata" journey wiped accounts so 104 of 127 journeys reported `The username or password you entered is incorrect`, identical on empty and seeded databases. Skill gains three questions a seed must answer, a use-case checklist, a destructive-action scan, a generic traps table with symptoms, measured expectations and a denominator checklist; routing trigger now fires on seed/test/demo data and empty pages. Independent review fixes: object ids follow the Mendix bigint pattern with a business-key guard (no uuids), associations are seeded where the page's path stores them, four new traps (enum names, inheritance chain, calculated attributes, view/external entities), and the port-offset and container-label traps moved to `harness-architecture.md`. — MendixMau
diff --git a/project-bin/_common.sh b/project-bin/_common.sh
index 48113307..27bbf05c 100755
--- a/project-bin/_common.sh
+++ b/project-bin/_common.sh
@@ -642,6 +642,18 @@ mxtk_mxbuild_why() {
   "$_py" -c "import json;d=json.load(open('$(native_path "$1")'));print('; '.join((e.get('message','') if isinstance(e,dict) else str(e)) for e in d.get('errors',[]) or [])[:300])" 2>/dev/null || true
 }
 
+# mxtk_copy_model_tree <model-dir> <dest-dir> — copy the model tree (the .mpr, mprcontents/ and
+# everything mxbuild reads beside them: widgets/, javasource/, theme/, userlib/ ...) into an
+# existing <dest-dir>. Leaves out .git, .mpr-snapshots, deployment, .mxcli (the LIVE app's
+# run --local record — a copy carrying it points app-restart.sh at the live app) and node_modules.
+# One routine for both scratch-copy users: bin/test-scratch.sh (mxcli test, #278) and
+# bin/exec.sh --on-copy (#350). tar preserves mtimes, which --on-copy relies on to tell the
+# files `mxcli exec` wrote from the files it copied. Returns tar's status.
+mxtk_copy_model_tree() {
+  tar -C "$1" --exclude=./.git --exclude=./.mpr-snapshots --exclude=./deployment \
+      --exclude=./.mxcli --exclude=./node_modules -cf - . | tar -C "$2" -xf -
+}
+
 # project_name — the .mpr basename without extension, for user-facing messages.
 project_name() {
   local mpr
diff --git a/project-bin/exec.sh b/project-bin/exec.sh
index b85dde08..f57c2859 100755
--- a/project-bin/exec.sh
+++ b/project-bin/exec.sh
@@ -17,7 +17,25 @@
 #        ./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.
+#        ./bin/exec.sh --on-copy <script.mdl>         (opt-in, or EXEC_ON_COPY=1: write a scratch
+#                                                     copy, promote it only on a clean gate)
+#        Leading flags (--cr, --commit-first, --on-copy, then --patch) may come in any order.
+#
+# --on-copy (opt-in, 2026-10-14, #350): `mxcli exec` and the mxbuild gate run on a scratch COPY
+# of the model (.mpr-snapshots/.on-copy/<stamp>/, the tree mxtk_copy_model_tree copies), and the
+# live model is written only by a promotion after a verified pass with exit 0. Without it, the
+# live model holds the script's changes from the first statement until the gate ends or the
+# snapshot is restored: 22-65 s per apply in the field, and forever if exec.sh is killed meanwhile.
+# Promotion refuses (live untouched, copy kept) when Studio Pro holds the model, even under
+# FORCE_EXEC, or when the live .mpr/mprcontents changed since the copy was taken (cksum manifest),
+# or when the copy is not on the model's filesystem (a rename would become a copy). The swap is
+# renames only: .mpr is replaced by one rename (atomic); mprcontents/ by two (live -> aside, new ->
+# live), so for the microseconds between them there is no mprcontents/ (rename(2) cannot exchange
+# two directories portably). Files `mxcli exec` wrote outside the model (javasource/ for a Java
+# action) are promoted the same way, one rename each; a file it DELETED there is not mirrored
+# (follow-up). A swap that fails half-way renames back, else restores the pre-exec snapshot. On any
+# other outcome the live model is never written and the copy is kept with a resume hint; the
+# newest MXTK_ON_COPY_KEEP (default 3) kept copies survive. Not with --patch (follow-up).
 #
 # --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
@@ -171,6 +189,7 @@ mxtk_change_class() {  # $1 = MDL script; prints "<class>\t<why>"
 # `[--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=""
+ON_COPY="${EXEC_ON_COPY:-0}"; [ "$ON_COPY" = 1 ] || ON_COPY=0; ON_COPY_FLAG=0
 while [ $# -gt 0 ]; do
   case "$1" in
     --cr)
@@ -185,6 +204,7 @@ while [ $# -gt 0 ]; do
       fi
       shift 2 ;;
     --commit-first) COMMIT_FIRST=1; shift ;;
+    --on-copy) ON_COPY=1; ON_COPY_FLAG=1; shift ;;
     --patch) PATCH_MODE=1; shift; break ;;
     --change-class|--watch-compat) ADVISORY="$1"; shift; break ;;
     *) break ;;
@@ -193,7 +213,7 @@ 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 "  Usage: ./bin/exec.sh [--commit-first] [--cr CR-NN] [--on-copy] <script.mdl>" >&2
     echo "         ./bin/exec.sh [--commit-first] [--cr CR-NN] --patch <script> [args...]" >&2
     exit 2 ;;
 esac
@@ -334,10 +354,18 @@ LOG_NAME="$(basename "$SCRIPT")"
 [ "$PATCH_MODE" = "1" ] && LOG_NAME="patch: $LOG_NAME"
 
 if [ -z "$SCRIPT" ]; then
-  echo "Usage: ./bin/exec.sh [--commit-first] [--cr CR-NN] <script.mdl>"
+  echo "Usage: ./bin/exec.sh [--commit-first] [--cr CR-NN] [--on-copy] <script.mdl>"
   echo "       ./bin/exec.sh [--commit-first] [--cr CR-NN] --patch <script> [args...]"
   exit 1
 fi
+if [ "$PATCH_MODE" = "1" ] && [ "$ON_COPY" = 1 ]; then
+  if [ "$ON_COPY_FLAG" = 1 ]; then
+    echo "✗ --on-copy does not take --patch yet (a patch already keeps only a verified write). Nothing was run." >&2
+    exit 2
+  fi
+  echo "  note: EXEC_ON_COPY=1 does not apply to --patch yet — this patch runs on the live model, as before."
+  ON_COPY=0
+fi
 if [ "$PATCH_MODE" = "1" ]; then
   # Resolve the path BEFORE the cd below, so a path relative to the caller's cwd keeps working.
   [ -f "$SCRIPT" ] || { echo "✗ --patch: no such file: $SCRIPT"; exit 1; }
@@ -383,6 +411,11 @@ BUILD_LOG="$PROJECT_ROOT/docs/BUILD-LOG.md"
 GATE_STATE="not-run"   # not-run | skipped | unverified | pass | fail
 GATE_ERRORS="?"        # mxbuild error count behind a pass (0 = clean); recorded in the stamp
 MXB_WHY=""             # mxbuild's errors[] reason when it exited without checking the model
+# --on-copy state (header): OC_PHASE pre | gate (exec + mxbuild on the copy) | done. While it is
+# `gate`, an "applied" row is held back (OC_PENDING_*) until the promotion has happened, so no row
+# says "applied" for a write the live model never received. OC_NOTE rides on every row.
+OC_PHASE="pre"; OC_NOTE=""; OC_PENDING_STATUS=""; OC_PENDING_DETAIL=""; OC_PENDING_APPLIED=""; OC_ROWS=0
+[ "$ON_COPY" = 1 ] && OC_NOTE="on-copy"
 
 # ── Exec approval (auto records itself) ──────────────────────────────────────
 # bin/exec-approval.sh decides ask vs auto; the ASKING happens before exec.sh ever runs (in
@@ -405,6 +438,10 @@ for _ea in "${MXTK_ROOT:-}/bin/exec-approval.sh" \
 done
 
 log_build() {   # $1=status  $2=detail
+  if [ "$ON_COPY" = 1 ] && [ "$OC_PHASE" = gate ]; then
+    case "$1" in *applied*) OC_PENDING_STATUS="$1"; OC_PENDING_DETAIL="$2"; return 0 ;; esac
+  fi
+  OC_ROWS=$((OC_ROWS + 1))
   mkdir -p "$(dirname "$BUILD_LOG")"
   [ -f "$BUILD_LOG" ] || cat > "$BUILD_LOG" <<'HDR'
 # Build log — auto-appended by bin/exec.sh
@@ -436,7 +473,7 @@ HDR2
   # The gate cell is read from GATE_STATE rather than passed in, so no caller
   # can omit it — a blank cell in this table reads as "fine", which is the exact
   # false-green the gate exists to prevent.
-  _detail="$2${CHANGE_CLASS:+ · change: $CHANGE_CLASS}${CR_ID:+ · cr: $CR_ID}$_EXEC_APPROVAL_SUFFIX"
+  _detail="$2${CHANGE_CLASS:+ · change: $CHANGE_CLASS}${CR_ID:+ · cr: $CR_ID}$_EXEC_APPROVAL_SUFFIX${OC_NOTE:+ · $OC_NOTE}"
   printf '| %s | `%s` | %s | %s | %s |\n' \
     "$(date '+%Y-%m-%dT%H:%M:%S%z')" "$LOG_NAME" \
     "${GATE_STATE:-not-run}" "$1" "$_detail" >> "$BUILD_LOG"
@@ -490,19 +527,23 @@ FORCE="${FORCE_EXEC:-0}"
 
 # 1. Studio Pro must not hold the project open (SP's in-memory model vs a direct
 #    file write = split-brain).
-SP_OPEN=0
-if [ -f "$MPR.lock" ]; then
+#    One test, used here and again by the --on-copy promotion right before it swaps.
+sp_holds_model() {  # 0 iff Studio Pro's <model>.mpr.lock names a live pid; sets SP_PID
+  SP_PID=""
+  [ -f "$MPR.lock" ] || return 1
   SP_PID=$(grep -oE '"ProcessId":[0-9]+' "$MPR.lock" 2>/dev/null | grep -oE '[0-9]+' || true)
-  if [ -n "$SP_PID" ] && kill -0 "$SP_PID" 2>/dev/null; then
-    SP_OPEN=1
-    echo "✗ Studio Pro has $NAME open (lock PID $SP_PID alive) — refusing exec (split-brain corruption risk)."
-    echo "  → Close the project in Studio Pro (or quit SP), then re-run."
-    echo "    Override (NOT recommended): FORCE_EXEC=1 ./bin/exec.sh $SCRIPT"
-    [ "$FORCE" = "1" ] || exit 1
-    echo "  (FORCE_EXEC set — proceeding despite open SP)"
-  elif [ -n "$SP_PID" ]; then
-    echo "  (stale $MPR_BASE.lock from dead PID $SP_PID — SP not actually open, proceeding)"
-  fi
+  [ -n "$SP_PID" ] && kill -0 "$SP_PID" 2>/dev/null
+}
+SP_OPEN=0
+if sp_holds_model; then
+  SP_OPEN=1
+  echo "✗ Studio Pro has $NAME open (lock PID $SP_PID alive) — refusing exec (split-brain corruption risk)."
+  echo "  → Close the project in Studio Pro (or quit SP), then re-run."
+  echo "    Override (NOT recommended): FORCE_EXEC=1 ./bin/exec.sh $SCRIPT"
+  [ "$FORCE" = "1" ] || exit 1
+  echo "  (FORCE_EXEC set — proceeding despite open SP)"
+elif [ -n "$SP_PID" ]; then
+  echo "  (stale $MPR_BASE.lock from dead PID $SP_PID — SP not actually open, proceeding)"
 fi
 
 # 2. One exec.sh at a time on THIS project (e.g. a second agent session on the same model).
@@ -869,6 +910,9 @@ run_lint_gate() {
 }
 # One place decides the applied-row wording, so both mxbuild-clean branches agree.
 log_applied() {  # $1 = mxbuild detail
+  # --on-copy: lint and score read the LIVE model, which does not hold the write yet. Held until
+  # the promotion, then called again by the promotion block below the gate.
+  if [ "$ON_COPY" = 1 ] && [ "$OC_PHASE" = gate ]; then OC_PENDING_APPLIED="$1"; return 0; fi
   run_lint_gate
   LINT_RC_FOR_LEDGER="$LINT_RC"
   take_score
@@ -949,9 +993,175 @@ if [ ! -x "$MXBUILD" ] || [ ! -x "$JAVA_EXE" ]; then
   fi
 fi
 
+# ── --on-copy: helpers (opt-in; header "--on-copy") ──────────────────────────
+# Defined for every run, used only when ON_COPY=1: the default path calls none of them.
+OC_ROOT="$PROJECT_ROOT/.mpr-snapshots/.on-copy"   # hidden: snapshot rotation (ls */) never sees it
+OC_KEEP="${MXTK_ON_COPY_KEEP:-3}"
+case "$OC_KEEP" in ''|*[!0-9]*|0) OC_KEEP=3 ;; esac
+OC_SCR=""; OC_COPY=""; OC_MPR=""; OC_FP0=""; OC_SIDE=""; OC_WHY=""; OC_LIVE_WRITTEN=0
+OC_COPY_MS=0; OC_SWAP_MS=0; OC_UNITS=0
+TARGET_MPR="$MPR"
+oc_ms() {  # wall clock in ms (GNU date); whole seconds x1000 where %N is not supported (BSD)
+  _n="$(date +%s%N 2>/dev/null)"
+  case "$_n" in ''|*[!0-9]*) echo $(( $(date +%s) * 1000 )) ;; *) echo $(( _n / 1000000 )) ;; esac
+}
+oc_fingerprint() {  # $1 = model dir. One cksum over the .mpr and every mprcontents/ file (name + bytes)
+  ( cd "$1" && { cksum "$MPR_BASE"
+      if [ -d mprcontents ]; then find mprcontents -type f | LC_ALL=C sort | tr '\n' '\0' | xargs -0 cksum; fi; } ) 2>/dev/null | cksum
+}
+oc_prune() {  # keep the newest $OC_KEEP kept copies
+  ls -dt "$OC_ROOT"/*/ 2>/dev/null | tail -n +$((OC_KEEP + 1)) | while read -r _d; do rm -rf "$_d"; done
+}
+oc_keep_hint() {
+  echo "  The copy is kept: $OC_COPY"
+  echo "    It holds what the script did. Look at it: ./mxcli -p $OC_MPR -c \"SHOW STRUCTURE\""
+  echo "  Resume: fix the script and re-run ./bin/exec.sh --on-copy $SCRIPT — it starts from a fresh copy"
+  echo "    of the live model. Resuming THIS copy with only the statements that did not land is not built"
+  echo "    yet (toolkit #350 follow-up)."
+  oc_prune
+  echo "  The newest $OC_KEEP kept copies stay under .mpr-snapshots/.on-copy/ (MXTK_ON_COPY_KEEP); older ones were removed."
+}
+oc_unstage() {  # put staged files back into the copy (nothing in the live model was replaced yet)
+  _t="$1"
+  [ -f "$MODEL_DIR/$_t.mpr" ] && mv "$MODEL_DIR/$_t.mpr" "$OC_COPY/$MPR_BASE" 2>/dev/null
+  [ -d "$MODEL_DIR/$_t.mprcontents" ] && mv "$MODEL_DIR/$_t.mprcontents" "$OC_COPY/mprcontents" 2>/dev/null
+  printf '%s\n' "$OC_SIDE" | while IFS= read -r _r; do
+    [ -n "$_r" ] && [ -f "$MODEL_DIR/$_r.$_t" ] && mv "$MODEL_DIR/$_r.$_t" "$OC_COPY/$_r" 2>/dev/null
+  done
+  return 0
+}
+# oc_promote — 0 promoted · 1 refused, the live model untouched · 2 the swap failed part-way
+# (rolled back by rename, else restored from the pre-exec snapshot; OC_WHY says which).
+oc_promote() {
+  _md="$MODEL_DIR"; _t=".mxtk-promote.$$"; _step=""
+  OC_WHY=""
+  if sp_holds_model; then
+    OC_WHY="Studio Pro holds $NAME (lock PID $SP_PID); its in-memory model would overwrite the promotion on its next save"; return 1
+  fi
+  # A rename across filesystems is a copy. ln (a hard link) fails across filesystems, on every platform.
+  : > "$OC_SCR/.fsprobe"
+  if ! ln "$OC_SCR/.fsprobe" "$_md/$_t.fsprobe" 2>/dev/null; then
+    rm -f "$OC_SCR/.fsprobe"
+    OC_WHY="the copy is not on the model's filesystem, so the swap could not be a rename"; return 1
+  fi
+  rm -f "$OC_SCR/.fsprobe" "$_md/$_t.fsprobe"
+  # Stage beside the live files (renames). Nothing live is replaced yet.
+  OC_UNITS=0
+  [ -d "$OC_COPY/mprcontents" ] && OC_UNITS=$(find "$OC_COPY/mprcontents" -type f | wc -l | tr -d ' ')
+  if ! mv "$OC_COPY/$MPR_BASE" "$_md/$_t.mpr" \
+     || { [ -d "$OC_COPY/mprcontents" ] && ! mv "$OC_COPY/mprcontents" "$_md/$_t.mprcontents"; }; then
+    oc_unstage "$_t"; OC_WHY="staging the copy beside the live model failed"; return 1
+  fi
+  _sidefail=0
+  while IFS= read -r _r; do
+    [ -n "$_r" ] || continue
+    mkdir -p "$_md/$(dirname "$_r")" && mv "$OC_COPY/$_r" "$_md/$_r.$_t" || { _sidefail=1; break; }
+  done <<OCSIDE
+$OC_SIDE
+OCSIDE
+  if [ "$_sidefail" = 1 ]; then oc_unstage "$_t"; OC_WHY="staging a file mxcli exec wrote outside the model failed"; return 1; fi
+  # Last checks, right before the swap: the live model is what was copied, and SP is still closed.
+  if [ "$(oc_fingerprint "$_md")" != "$OC_FP0" ]; then
+    oc_unstage "$_t"
+    OC_WHY="the live model changed since the copy was taken (Studio Pro save, git checkout, another writer); promoting would drop that change"; return 1
+  fi
+  if sp_holds_model; then
+    oc_unstage "$_t"; OC_WHY="Studio Pro opened $NAME (lock PID $SP_PID) during the exec"; return 1
+  fi
+  # The swap: renames only. Old files stay beside the new ones until the swap is verified.
+  _s0=$(oc_ms); OC_LIVE_WRITTEN=1
+  { ln "$_md/$MPR_BASE" "$_md/$_t.old.mpr" 2>/dev/null || cp -p "$_md/$MPR_BASE" "$_md/$_t.old.mpr"; } || { oc_unstage "$_t"; OC_LIVE_WRITTEN=0; OC_WHY="could not keep the old .mpr aside"; return 1; }
+  _ok=1
+  if [ -d "$_md/mprcontents" ]; then
+    if mv "$_md/mprcontents" "$_md/$_t.old.mprcontents"; then _step="aside"; else _ok=0; fi
+  fi
+  if [ "$_ok" = 1 ] && [ -d "$_md/$_t.mprcontents" ]; then
+    if mv "$_md/$_t.mprcontents" "$_md/mprcontents"; then _step="$_step in"; else _ok=0; fi
+  fi
+  [ "${_MXTK_TEST_SWAP_FAIL:-}" = mpr ] && _ok=0   # fixture hook: fail between the two halves
+  if [ "$_ok" = 1 ]; then
+    if mv -f "$_md/$_t.mpr" "$_md/$MPR_BASE"; then _step="$_step mpr"; else _ok=0; fi
+  fi
+  _sides=""
+  if [ "$_ok" = 1 ]; then
+    while IFS= read -r _r; do
+      [ -n "$_r" ] || continue
+      [ -f "$_md/$_r" ] && { ln "$_md/$_r" "$_md/$_r.$_t.old" 2>/dev/null || cp -p "$_md/$_r" "$_md/$_r.$_t.old"; }
+      if mv -f "$_md/$_r.$_t" "$_md/$_r"; then _sides="$_sides
+$_r"; else _ok=0; break; fi
+    done <<OCSIDE
+$OC_SIDE
+OCSIDE
+  fi
+  _s1=$(oc_ms)   # the renames are done: this is the end of the window the live model is mixed
+  if [ "$_ok" = 1 ] && [ "$OC_UNITS" -gt 0 ] \
+     && [ "$(find "$_md/mprcontents" -type f 2>/dev/null | wc -l | tr -d ' ')" -ne "$OC_UNITS" ]; then
+    _ok=0
+  fi
+  if [ "$_ok" = 1 ]; then
+    OC_SWAP_MS=$(( _s1 - _s0 ))
+    # Old files out of the model dir, into the scratch dir, then the scratch dir goes.
+    [ -d "$_md/$_t.old.mprcontents" ] && mv "$_md/$_t.old.mprcontents" "$OC_SCR/old-mprcontents"
+    rm -f "$_md/$_t.old.mpr"
+    printf '%s\n' "$OC_SIDE" | while IFS= read -r _r; do [ -n "$_r" ] && rm -f "$_md/$_r.$_t.old"; done
+    return 0
+  fi
+  # Part-way failure: undo by rename, newest step first; anything that fails -> the snapshot.
+  _back=1
+  printf '%s\n' "$_sides" | while IFS= read -r _r; do
+    [ -n "$_r" ] || continue
+    if [ -f "$_md/$_r.$_t.old" ]; then mv -f "$_md/$_r.$_t.old" "$_md/$_r"; else rm -f "$_md/$_r"; fi
+  done
+  case "$_step" in *mpr*) mv -f "$_md/$_t.old.mpr" "$_md/$MPR_BASE" || _back=0 ;; *) rm -f "$_md/$_t.old.mpr" ;; esac
+  case "$_step" in *in*) mv "$_md/mprcontents" "$OC_SCR/failed-mprcontents" || _back=0 ;; esac
+  case "$_step" in *aside*) mv "$_md/$_t.old.mprcontents" "$_md/mprcontents" || _back=0 ;; esac
+  rm -rf "$_md/$_t.mprcontents" "$_md/$_t.mpr"
+  printf '%s\n' "$OC_SIDE" | while IFS= read -r _r; do [ -n "$_r" ] && rm -f "$_md/$_r.$_t" "$_md/$_r.$_t.old"; done
+  if [ "$_back" = 1 ] && [ "$(oc_fingerprint "$_md")" = "$OC_FP0" ]; then
+    OC_WHY="the swap failed part-way (after: ${_step# }); renamed back — the live model is byte-identical to before"
+  else
+    restore_snapshot
+    OC_WHY="the swap failed part-way and could not be renamed back; $([ "$RESTORED" = 1 ] && echo 'restored from the pre-exec snapshot' || echo 'the RESTORE FAILED too — see above')"
+  fi
+  return 2
+}
+
+if [ "$ON_COPY" = 1 ]; then
+  # A promotion killed between its renames leaves .mxtk-promote.* beside the model: refuse, name the fix.
+  _left="$(ls -d "$MODEL_DIR"/.mxtk-promote.* 2>/dev/null | head -3 | tr '\n' ' ')"
+  if [ -n "$_left" ]; then
+    echo "✗ --on-copy: an earlier promotion was interrupted — left behind: $_left"
+    echo "  → ./bin/restore-mpr.sh (newest snapshot = the model before that exec), then remove those paths, then re-run."
+    log_build "🚫 blocked" "on-copy: interrupted promotion left .mxtk-promote.* beside the model"
+    exit 1
+  fi
+  if ! type mxtk_copy_model_tree >/dev/null 2>&1; then
+    echo "✗ --on-copy: bin/_common.sh predates mxtk_copy_model_tree — run the toolkit's bin/sync-project.sh. Nothing was written."
+    exit 1
+  fi
+  OC_FP0="$(oc_fingerprint "$MODEL_DIR")"   # taken BEFORE the snapshot and the copy
+fi
+
 echo "→ Snapshotting model..."
 ./bin/snapshot-mpr.sh
 
+if [ "$ON_COPY" = 1 ]; then
+  mkdir -p "$OC_ROOT"
+  OC_SCR="$OC_ROOT/$(date +%Y%m%d-%H%M%S)-$$"; OC_COPY="$OC_SCR/model"; OC_MPR="$OC_COPY/$MPR_BASE"
+  mkdir -p "$OC_COPY"
+  _c0=$(oc_ms)
+  if ! mxtk_copy_model_tree "$MODEL_DIR" "$OC_COPY" || [ ! -f "$OC_MPR" ]; then
+    rm -rf "$OC_SCR"
+    echo "✗ --on-copy: copying the model to $OC_SCR failed — nothing was written."
+    log_build "🚫 blocked" "on-copy: copying the model failed — nothing written"
+    exit 1
+  fi
+  OC_COPY_MS=$(( $(oc_ms) - _c0 ))
+  TARGET_MPR="$OC_MPR"
+  echo "→ on-copy: model copied in ${OC_COPY_MS} ms to $OC_COPY"
+  echo "  mxcli exec and the mxbuild gate run there; the live model is written only by a promotion after a clean gate."
+fi
+
 # ── Restore (one implementation) ─────────────────────────────────────────────
 # Rolls the model back to the snapshot just taken, through restore-mpr.sh. exec.sh used to
 # carry an inline copy of it that had only the mprcontents/ (v2) arm, so on a v1 single-file
@@ -962,6 +1172,11 @@ RESTORED=0
 RESTORE_TRIED=0
 restore_snapshot() {
   RESTORE_TRIED=1
+  if [ "$ON_COPY" = 1 ] && [ "$OC_LIVE_WRITTEN" != 1 ]; then
+    RESTORED=1
+    echo "  → on-copy: the live model was never written — nothing to restore (the copy holds the script's changes)."
+    return 0
+  fi
   NEWEST_SNAP=$(ls -dt "$PROJECT_ROOT/.mpr-snapshots"/[0-9]*/ 2>/dev/null | head -1)
   RESTORER="$(dirname "$0")/restore-mpr.sh"
   if [ -z "$NEWEST_SNAP" ] || [ ! -f "$NEWEST_SNAP/$MPR_BASE" ]; then
@@ -1264,14 +1479,28 @@ if [ "$PATCH_MODE" = "1" ]; then
     exit "$EXEC_STATUS"
   fi
 else
-  "${PMXCLI:-./mxcli}" exec "$SCRIPT" -p "$MPR" || EXEC_STATUS=$?
+  if [ "$ON_COPY" = 1 ]; then
+    OC_PHASE="gate"; OC_NOTE="on-copy: live model not written, copy kept at $OC_SCR"
+    : > "$OC_SCR/.exec-start"   # tar kept the copied files' mtimes: anything newer, exec wrote
+  fi
+  "${PMXCLI:-./mxcli}" exec "$SCRIPT" -p "$TARGET_MPR" || EXEC_STATUS=$?
+  if [ "$ON_COPY" = 1 ]; then
+    # Files exec wrote OUTSIDE the model (javasource/ for a Java action): promoted with the model.
+    # Listed now, before mxbuild writes its own output into the copy.
+    OC_SIDE="$(cd "$OC_COPY" && find . \( -path ./mprcontents -o -path ./deployment -o -path ./.mxcli \
+                 -o -path ./.git -o -path ./node_modules \) -prune -o -type f -newer "$OC_SCR/.exec-start" -print \
+               2>/dev/null | sed 's|^\./||' | while IFS= read -r _r; do
+                 case "$_r" in "$MPR_BASE"|"$MPR_BASE".*) ;; *) printf '%s\n' "$_r" ;; esac
+               done)"
+    [ -n "$OC_SIDE" ] && echo "  on-copy: mxcli exec also wrote $(printf '%s\n' "$OC_SIDE" | grep -c .) file(s) outside the model; they are promoted with it: $(printf '%s' "$OC_SIDE" | head -3 | tr '\n' ' ')"
+  fi
 fi
 
 if [ "$EXEC_STATUS" -ne 0 ]; then
   echo ""
   echo "  ✗ mxcli exec exited $EXEC_STATUS — PARTIAL APPLICATION LIKELY."
   echo "    mxcli is not transactional across statements: everything before the"
-  echo "    failing statement is already in the model. Running the gate anyway."
+  echo "    failing statement is already in the $([ "$ON_COPY" = 1 ] && echo 'COPY (not the live model)' || echo model). Running the gate anyway."
 fi
 
 echo ""
@@ -1300,7 +1529,7 @@ if [ -x "$MXBUILD" ] && [ -x "$JAVA_EXE" ]; then
   # discarded here: this call site keeps its own file-presence/exit-code
   # branching below unchanged, computing CE_COUNT via err_count once it knows
   # which branch applies.
-  mxtk_mxbuild_error_count "$MPR" "${MXTK_GATE_TIMEOUT:-0}" "$ERRORS_FILE" >/dev/null || true
+  mxtk_mxbuild_error_count "$TARGET_MPR" "${MXTK_GATE_TIMEOUT:-0}" "$ERRORS_FILE" >/dev/null || true
   MXBUILD_EXIT="$MXTK_MXBUILD_EXIT"
   MXBUILD_OUT="$MXTK_MXBUILD_OUT"
   MXB_WHY="${MXTK_MXBUILD_WHY:-}"
@@ -1486,6 +1715,49 @@ else
   echo "  → Verify manually in SP before proceeding."
 fi
 
+# ── --on-copy: promote, or leave the live model alone ────────────────────────
+# Promotes only a verified pass of a fully applied script. Every other outcome — a failed or
+# unverifiable gate, a non-zero mxcli exec (a PARTIAL application, on the copy only) — leaves the
+# live model as it was and keeps the copy. Rows held back during the gate are written after it.
+if [ "$ON_COPY" = 1 ]; then
+  OC_PHASE="decide"
+  if [ "$GATE_STATE" = pass ] && [ "$EXEC_STATUS" -eq 0 ]; then
+    echo ""
+    echo "→ on-copy: the gate passed on the copy — promoting it to the live model..."
+    _oc_rc=0; oc_promote || _oc_rc=$?
+    OC_PHASE="done"
+    if [ "$_oc_rc" -eq 0 ]; then
+      OC_NOTE="on-copy: promoted (copy ${OC_COPY_MS} ms, swap ${OC_SWAP_MS} ms)"
+      echo "  ✓ promoted by rename in ${OC_SWAP_MS} ms (copy took ${OC_COPY_MS} ms); scratch copy removed."
+      rm -rf "$OC_SCR"
+      if [ -n "$OC_PENDING_APPLIED" ]; then log_applied "$OC_PENDING_APPLIED"
+      elif [ -n "$OC_PENDING_STATUS" ]; then log_build "$OC_PENDING_STATUS" "$OC_PENDING_DETAIL"; fi
+    elif [ "$_oc_rc" -eq 1 ]; then
+      OC_NOTE="on-copy: NOT promoted, live model untouched, copy kept at $OC_SCR"
+      echo "✗ on-copy: promotion REFUSED — $OC_WHY."
+      echo "  The live model was not written. The gate passed on the copy, so the script itself is fine."
+      oc_keep_hint
+      log_build "🚫 not promoted" "gate passed on the copy; promotion refused: $OC_WHY"
+      exit 1
+    else
+      OC_NOTE="on-copy: promotion failed part-way"
+      echo "✗ on-copy: $OC_WHY."
+      oc_keep_hint
+      if [ -x ./bin/model-stamp.sh ]; then ./bin/model-stamp.sh clear >/dev/null 2>&1 || true; fi
+      log_build "❌ promotion failed" "$OC_WHY"
+      exit 1
+    fi
+  else
+    OC_PHASE="done"
+    echo ""
+    echo "✗ on-copy: NOT promoted (gate $GATE_STATE, mxcli exec exit $EXEC_STATUS) — the live model was never written."
+    oc_keep_hint
+    [ "$OC_ROWS" -eq 0 ] && log_build "❌ not promoted" "gate $GATE_STATE, mxcli exec exit $EXEC_STATUS on the copy; live model not written"
+    [ "$EXEC_STATUS" -ne 0 ] && exit "$EXEC_STATUS"
+    exit 1
+  fi
+fi
+
 # ── --patch: keep only a verified write ──────────────────────────────────────
 # A failed gate has already restored above (RESTORE_TRIED=1). What is left is a gate that could
 # not run or could not verify — which an MDL run keeps, flagged, and a patch does not.
diff --git a/project-bin/test-scratch.sh b/project-bin/test-scratch.sh
index d20192cf..d9573fb6 100755
--- a/project-bin/test-scratch.sh
+++ b/project-bin/test-scratch.sh
@@ -250,8 +250,7 @@ take_lock "$EXEC_LOCK" "this project's model (an exec.sh is writing it)" || exit
 # 2. The copy.
 SCRATCH="$(mktemp -d "${MXTK_SCRATCH_DIR:-${TMPDIR:-/tmp}}/$(basename "$MPR_NAME" .mpr)-test.XXXXXX")" || exit 3
 echo "→ test-scratch: copying $(basename "$MODEL_DIR")/ → $SCRATCH (no .git, .mpr-snapshots, deployment, .mxcli)"
-if ! tar -C "$MODEL_DIR" --exclude=./.git --exclude=./.mpr-snapshots --exclude=./deployment \
-       --exclude=./.mxcli --exclude=./node_modules -cf - . | tar -C "$SCRATCH" -xf -; then
+if ! mxtk_copy_model_tree "$MODEL_DIR" "$SCRATCH"; then
   echo "✗ test-scratch: copy failed." >&2; exit 3
 fi
 release "$EXEC_LOCK"
diff --git a/skills/iterative-build-loop.md b/skills/iterative-build-loop.md
index c538d425..b16bee12 100644
--- a/skills/iterative-build-loop.md
+++ b/skills/iterative-build-loop.md
@@ -293,6 +293,8 @@ is the part worth stating twice.
 | `last-mxbuild-errors.json` is cleared at the **start** of a run, not on success | An interrupted run must not leave a previous failure's file looking like its own report |
 | Studio Pro is never auto-killed; the reopen is offered, then done on a yes | See the SP Lifecycle Rule above |
 
+**Opt-in: `./bin/exec.sh --on-copy <script>` (or `EXEC_ON_COPY=1`).** By default the live model holds the script's unverified write for the length of the gate, and keeps it if exec.sh is killed. With `--on-copy`, `mxcli exec` and the mxbuild gate run on a scratch copy under the same lock. The live model is written only by a rename-based promotion after a verified pass with exit 0. Promotion is refused while Studio Pro holds the model (even under `FORCE_EXEC`) and when the live model changed since the copy was taken. On any refusal or failure the live model is byte-identical and the copy is kept under `.mpr-snapshots/.on-copy/`, with a resume hint. It is stub-tested only and not yet the default (toolkit #350).
+
 ### Standalone SP restart — `bin/restart-sp.sh`
 
 Only run this when the user explicitly asks to restart SP. Invoke the binary directly — `open -a` can trigger macOS's file-association picker in some environments:
diff --git a/tests/wave2/bench-exec-on-copy.sh b/tests/wave2/bench-exec-on-copy.sh
new file mode 100755
index 00000000..cb747ca3
--- /dev/null
+++ b/tests/wave2/bench-exec-on-copy.sh
@@ -0,0 +1,179 @@
+#!/usr/bin/env bash
+# bench-exec-on-copy.sh — before/after measurement for exec.sh --on-copy (#350).
+#
+# Usage: bash tests/wave2/bench-exec-on-copy.sh [path-to-exec.sh]
+#   BENCH_MXB_SECS=2          stub mxbuild duration per run (an INPUT, not a measurement: real
+#                             mxbuild took 22-65 s per apply in the field, iterative-build-loop.md)
+#   BENCH_SIZES="500 5000 20000"   synthetic mprcontents/ file counts
+#   BENCH_RUNS=3              clean runs per path per size (the median is reported)
+#   BENCH_FAIL_RUNS=10        failure-injection runs per path, per failure kind, per size
+#   BENCH_UNIT_BYTES=1024     bytes per synthetic unit
+#
+# What it measures, per size, default path vs --on-copy, with the real exec.sh, snapshot-mpr.sh,
+# restore-mpr.sh and _common.sh and stub mxcli/mxbuild (no real model, mxcli or mxbuild):
+#   broken window  how long the live model holds an unverified write. A poller cksums the live
+#                  .mpr + mprcontents/ in a loop. Default: from the first poll that sees the write
+#                  to the stub mxbuild's end (clean) or to the first poll back at the original
+#                  (failed gate, restored). On-copy: polls that saw a state that is neither the
+#                  original nor the promoted one, and exec.sh's own swap timer.
+#   overhead       on-copy copy + swap (exec.sh's timers) and the wall-clock delta of a whole run.
+#   failure share  runs whose live model is byte-identical after a failed exec: (a) the gate
+#                  reports a new error, (b) exec.sh is SIGKILLed while mxbuild runs (a crash, a
+#                  closed terminal, Ctrl-C twice).
+# Prints a markdown table, one row per size as it completes. Needs GNU date (%N) for millisecond timing. Takes minutes, not seconds.
+set -uo pipefail
+
+TOOLKIT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+SUBJECT="${1:-$TOOLKIT/project-bin/exec.sh}"
+case "$SUBJECT" in /*) ;; *) SUBJECT="$PWD/$SUBJECT" ;; esac
+MXB_SECS="${BENCH_MXB_SECS:-2}"
+SIZES="${BENCH_SIZES:-500 5000 20000}"
+RUNS="${BENCH_RUNS:-3}"
+FRUNS="${BENCH_FAIL_RUNS:-10}"
+UBYTES="${BENCH_UNIT_BYTES:-1024}"
+case "$(date +%N)" in *[!0-9]*|'') echo "bench-exec-on-copy: needs GNU date (%N) for ms timing" >&2; exit 2 ;; esac
+ms() { echo $(( $(date +%s%N) / 1000000 )); }
+
+WORK="$(mktemp -d "${TMPDIR:-/tmp}/benchcopy.XXXXXX")" || exit 2
+export GIT_CEILING_DIRECTORIES="$WORK"   # no git repo: exec.sh's uncommitted-model guard stays quiet
+POLLER=""
+cleanup() { [ -n "$POLLER" ] && kill "$POLLER" 2>/dev/null; pkill -f "$WORK/" 2>/dev/null; rm -rf "$WORK"; }
+trap cleanup EXIT
+
+mkdir -p "$WORK/jdk/bin" "$WORK/stubs"
+printf '#!/bin/sh\nexit 0\n' > "$WORK/jdk/bin/java"; chmod +x "$WORK/jdk/bin/java"
+cat > "$WORK/stubs/mxbuild" <<'MXB'
+#!/usr/bin/env bash
+ef=""; for a in "$@"; do case "$a" in --write-errors=*) ef="${a#--write-errors=}" ;; esac; done
+echo "$$" > "$STUB_LOG/mxbuild.pid"
+echo "start $(( $(date +%s%N) / 1000000 ))" >> "$STUB_LOG/mxbuild.times"
+sleep "$BENCH_MXB_SECS"
+echo "end $(( $(date +%s%N) / 1000000 ))" >> "$STUB_LOG/mxbuild.times"
+if [ "${STUB_MXB_ERR:-0}" = 1 ] && [ ! -f "$STUB_LOG/mxbuild.erred" ]; then
+  : > "$STUB_LOG/mxbuild.erred"   # only the gate fails; the attribution rebuild on the restored model is clean
+  printf '{"problems":[{"severity":"Error","errorCode":"CE0117","message":"Error(s) in expression.","locations":[{"module":"M","document":"D","element":"E"}]}]}' > "$ef"
+  exit 1
+fi
+printf '{"problems":[]}' > "$ef"; exit 0
+MXB
+chmod +x "$WORK/stubs/mxbuild"
+
+mktemplate() {  # $1 = dir, $2 = unit count
+  local T="$1" n="$2" i d pad
+  mkdir -p "$T/bin" "$T/mdlsource" "$T/javasource/m"
+  pad="$(head -c "$UBYTES" /dev/zero | tr '\0' 'x')"
+  printf 'model index\n%s\n' "$pad" > "$T/Bench.mpr"
+  i=0
+  while [ "$i" -lt "$n" ]; do
+    d="$T/mprcontents/$(printf '%02x' $((i % 256)))/$(printf '%02x' $(((i / 256) % 256)))"
+    [ -d "$d" ] || mkdir -p "$d"
+    printf 'unit %d\n%s\n' "$i" "$pad" > "$d/u$i.mxunit"
+    i=$((i + 1))
+  done
+  printf 'class Old {}\n' > "$T/javasource/m/Old.java"
+  printf 'CREATE MODULE "Bench";\n' > "$T/mdlsource/b.mdl"
+  cp "$TOOLKIT/project-bin/_common.sh" "$TOOLKIT/project-bin/restore-mpr.sh" "$TOOLKIT/project-bin/snapshot-mpr.sh" "$T/bin/"
+  cp "$SUBJECT" "$T/bin/exec.sh"
+  # mxcli exec: rewrites the .mpr and 10 units of whatever model -p names (a typical small script).
+  cat > "$T/mxcli" <<'MXCLI'
+#!/usr/bin/env bash
+[ "${1:-}" = exec ] || exit 0
+m=""; while [ $# -gt 0 ]; do [ "$1" = -p ] && m="$2"; shift; done
+d="$(dirname "$m")"
+echo "exec-start $(( $(date +%s%N) / 1000000 ))" >> "$STUB_LOG/exec.times"
+echo "changed $$" >> "$m"
+for u in $(find "$d/mprcontents" -name '*.mxunit' | head -10); do echo "changed" >> "$u"; done
+exit 0
+MXCLI
+  chmod +x "$T/bin/"*.sh "$T/mxcli"
+}
+live_fp() {  # $1 = project: cksum of the live .mpr + every mprcontents file
+  ( cd "$1" && { cksum Bench.mpr; find mprcontents -type f | LC_ALL=C sort | tr '\n' '\0' | xargs -0 cksum; } ) 2>/dev/null | cksum | cut -d' ' -f1
+}
+start_poller() {  # $1 = project, $2 = out file. Polls until killed.
+  ( while :; do printf '%s %s\n' "$(ms)" "$(live_fp "$1")" >> "$2"; done ) &
+  POLLER=$!
+}
+stop_poller() { [ -n "$POLLER" ] && { kill "$POLLER" 2>/dev/null; wait "$POLLER" 2>/dev/null; }; POLLER=""; }
+run_exec() {  # $1 = project, $2 = log dir, rest = exec.sh args; prints exec.sh output
+  local P="$1" L="$2"; shift 2
+  ( cd "$P" && STUB_LOG="$L" BENCH_MXB_SECS="$MXB_SECS" JAVA_HOME="$WORK/jdk" SKIP_BASELINE=1 SP_RESTART=0 \
+      MXTK_NO_INSTALL=1 MXTK_NO_SCORE=1 SKIP_DOCTOR=1 MXBUILD_PATH="$WORK/stubs/mxbuild" ./bin/exec.sh "$@" ) 2>&1
+}
+median() { sort -n | awk '{a[NR]=$1} END { if (NR == 0) print "-"; else print a[int((NR + 1) / 2)] }'; }
+
+# One clean or gate-failing run with the poller. Prints "<window_ms> <mixed_polls> <polls> <wall_ms> <copy_ms> <swap_ms> <poll_period_ms>"
+measure() {  # $1 = template, $2 = mode default|copy, $3 = STUB_MXB_ERR
+  local P="$WORK/run" L="$WORK/log" PF="$WORK/poll" S0 SF OUT t0 t1 first win mixed n per cms sms flag=""
+  rm -rf "$P" "$L" "$PF"; cp -R "$1" "$P"; mkdir -p "$L"
+  [ "$2" = copy ] && flag="--on-copy"
+  S0="$(live_fp "$P")"
+  start_poller "$P" "$PF"; sleep 0.3
+  t0=$(ms); OUT="$(STUB_MXB_ERR="$3" run_exec "$P" "$L" $flag mdlsource/b.mdl)"; t1=$(ms)
+  sleep 0.3; stop_poller
+  SF="$(live_fp "$P")"
+  n=$(wc -l < "$PF" | tr -d ' ')
+  per=$(awk 'NR==1{f=$1} {l=$1} END{ if (NR>1) printf "%d", (l-f)/(NR-1); else print 0 }' "$PF")
+  mend=$(awk '$1=="end"{print $2; exit}' "$L/mxbuild.times" 2>/dev/null)
+  if [ "$2" = default ]; then
+    first=$(awk -v s="$S0" '$2!=s{print $1; exit}' "$PF")
+    if [ "$3" = 1 ]; then  # window ends when the live model is back at the original
+      win=$(awk -v s="$S0" -v f="${first:-0}" '$1>f && $2==s {print $1 - f; exit}' "$PF")
+    else
+      win=$(( ${mend:-0} - ${first:-0} ))
+    fi
+    mixed=0
+  else
+    win=$(printf '%s\n' "$OUT" | sed -n 's/.*promoted by rename in \([0-9]*\) ms.*/\1/p' | head -1)
+    [ -n "$win" ] || win=0
+    mixed=$(awk -v s="$S0" -v f="$SF" '$2!=s && $2!=f' "$PF" | wc -l | tr -d ' ')
+  fi
+  cms=$(printf '%s\n' "$OUT" | sed -n 's/.*model copied in \([0-9]*\) ms.*/\1/p' | head -1)
+  sms=$(printf '%s\n' "$OUT" | sed -n 's/.*promoted by rename in \([0-9]*\) ms.*/\1/p' | head -1)
+  echo "${win:-?} $mixed $n $((t1 - t0)) ${cms:-0} ${sms:-0} $per"
+}
+# Failure injection: prints 1 if the live model is byte-identical afterwards, else 0.
+inject() {  # $1 = template, $2 = mode, $3 = gate|kill
+  local P="$WORK/run" L="$WORK/log" S0 flag="" pid i
+  rm -rf "$P" "$L"; cp -R "$1" "$P"; mkdir -p "$L"
+  [ "$2" = copy ] && flag="--on-copy"
+  S0="$(live_fp "$P")"
+  if [ "$3" = gate ]; then
+    STUB_MXB_ERR=1 run_exec "$P" "$L" $flag mdlsource/b.mdl >/dev/null
+  else
+    ( cd "$P" && exec env STUB_LOG="$L" BENCH_MXB_SECS="$MXB_SECS" JAVA_HOME="$WORK/jdk" SKIP_BASELINE=1 SP_RESTART=0 \
+        MXTK_NO_INSTALL=1 MXTK_NO_SCORE=1 SKIP_DOCTOR=1 MXBUILD_PATH="$WORK/stubs/mxbuild" ./bin/exec.sh $flag mdlsource/b.mdl ) >/dev/null 2>&1 &
+    pid=$!
+    for i in $(seq 1 600); do [ -s "$L/mxbuild.pid" ] && break; sleep 0.05; done
+    kill -KILL "$pid" 2>/dev/null; kill -KILL "$(cat "$L/mxbuild.pid" 2>/dev/null)" 2>/dev/null
+    wait "$pid" 2>/dev/null
+  fi
+  [ "$(live_fp "$P")" = "$S0" ] && echo 1 || echo 0
+}
+
+echo "bench-exec-on-copy: subject $SUBJECT"
+echo "stub mxbuild ${MXB_SECS}s per run (input) · $RUNS clean runs per path (median) · $FRUNS failure runs per path per kind · ${UBYTES}-byte units"
+echo ""
+echo "| units | broken window, default (ms) | broken window, on-copy (ms) | mixed-state polls on-copy | poll period (ms) | copy (ms) | swap (ms) | wall default → on-copy (ms) | gate-fail: live identical default / on-copy | killed mid-gate: live identical default / on-copy |
+|---:|---:|---:|---:|---:|---:|---:|---:|---|---|"
+for N in $SIZES; do
+  T="$WORK/tpl-$N"; rm -rf "$T"; mktemplate "$T" "$N"
+  echo "-- $N units: clean runs" >&2
+  : > "$WORK/d"; : > "$WORK/c"
+  for r in $(seq 1 "$RUNS"); do measure "$T" default 0 >> "$WORK/d"; measure "$T" copy 0 >> "$WORK/c"; done
+  echo "-- $N units: gate-failure window" >&2
+  DF="$(measure "$T" default 1)"
+  DWIN=$(cut -d' ' -f1 "$WORK/d" | median); CWIN=$(cut -d' ' -f1 "$WORK/c" | median)
+  MIX=$(awk '{m+=$2; n+=$3} END {printf "%d of %d", m, n}' "$WORK/c")
+  PER=$(cut -d' ' -f7 "$WORK/c" | median)
+  CPY=$(cut -d' ' -f5 "$WORK/c" | median); SWP=$(cut -d' ' -f6 "$WORK/c" | median)
+  WD=$(cut -d' ' -f4 "$WORK/d" | median); WC=$(cut -d' ' -f4 "$WORK/c" | median)
+  echo "-- $N units: failure injection" >&2
+  GD=0; GC=0; KD=0; KC=0
+  for r in $(seq 1 "$FRUNS"); do
+    GD=$((GD + $(inject "$T" default gate))); GC=$((GC + $(inject "$T" copy gate)))
+    KD=$((KD + $(inject "$T" default kill))); KC=$((KC + $(inject "$T" copy kill)))
+  done
+  echo "| $N | $DWIN clean · $(echo "$DF" | cut -d' ' -f1) failed gate | $CWIN | $MIX | $PER | $CPY | $SWP | $WD → $WC (+$((WC - WD))) | $GD/$FRUNS / $GC/$FRUNS | $KD/$FRUNS / $KC/$FRUNS |"
+  rm -rf "$T"
+done
diff --git a/tests/wave2/test-exec-on-copy.sh b/tests/wave2/test-exec-on-copy.sh
new file mode 100755
index 00000000..3bf51a54
--- /dev/null
+++ b/tests/wave2/test-exec-on-copy.sh
@@ -0,0 +1,236 @@
+#!/usr/bin/env bash
+# test-exec-on-copy.sh — exec.sh --on-copy / EXEC_ON_COPY=1 (#350): write a scratch copy, promote
+# it only on a clean gate.
+#
+# Usage: bash tests/wave2/test-exec-on-copy.sh [path-to-exec.sh]
+#
+# WHY (#350, external review 2026-10-14). The default path writes the live model, then runs
+# mxbuild, then restores on failure: for the length of the gate (22-65 s per apply in the field,
+# iterative-build-loop.md) the live model holds an unverified write, and a killed exec.sh leaves
+# it there. --on-copy runs exec and the gate on a copy and promotes by rename.
+#
+# Covers, on BOTH layouts (.mpr at the root, and under app/):
+#   clean copy-exec promotes: exec and mxbuild ran on the copy, the live model gains the change
+#     (.mpr, a changed unit, a new unit, a file written outside the model), one applied row, the
+#     scratch copy is removed;
+#   failing gate: live model byte-identical, copy kept with the change, resume hint, one row;
+#   mxcli exec exit 1 (partial, on the copy): live byte-identical, exit code passed through;
+#   live model modified during the exec: promotion refused, the concurrent change survives,
+#     exec's change is not promoted;
+#   Studio Pro opens the project during the exec: promotion refused, live byte-identical;
+#   a swap that fails half-way (fixture hook) is renamed back: live byte-identical;
+#   EXEC_ON_COPY=1 is the same as --on-copy; flag unset runs on the live model as before;
+#   kept copies are pruned to MXTK_ON_COPY_KEEP; --on-copy --patch is refused; EXEC_ON_COPY=1
+#   with --patch runs the patch as before; leftovers of an interrupted promotion refuse.
+# Stub mxcli and mxbuild record the model path they were given. No real model, mxcli or mxbuild.
+set -uo pipefail
+
+TOOLKIT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+SUBJECT="${1:-$TOOLKIT/project-bin/exec.sh}"
+case "$SUBJECT" in /*) ;; *) SUBJECT="$PWD/$SUBJECT" ;; esac
+WORK="$(mktemp -d "${TMPDIR:-/tmp}/execcopy.XXXXXX")" || exit 2
+BG=""
+cleanup() { for p in $BG; do kill -KILL "$p" 2>/dev/null; done; rm -rf "$WORK"; }
+trap cleanup EXIT
+PASS=0; FAIL=0
+ok()  { PASS=$((PASS+1)); echo "  ok   — $1"; }
+bad() { FAIL=$((FAIL+1)); echo "  FAIL — $1"; }
+has() { case "$2" in *"$3"*) ok "$1" ;; *) bad "$1 — missing '$3' in: $(printf '%s' "$2" | tail -6)" ;; esac; }
+hasnt() { case "$2" in *"$3"*) bad "$1 — unexpected '$3'" ;; *) ok "$1" ;; esac; }
+echo "== subject: $SUBJECT"
+
+# ── Stubs ────────────────────────────────────────────────────────────────────
+mkdir -p "$WORK/jdk/bin"
+printf '#!/bin/sh\nexit 0\n' > "$WORK/jdk/bin/java"; chmod +x "$WORK/jdk/bin/java"
+# mxbuild: records its model path; STUB_MXB_ERR=1 reports a new error; STUB_MXB_TOUCH=<file>
+# appends to that (live) file mid-gate; STUB_MXB_SP=<lockfile> makes Studio Pro "open" the model.
+cat > "$WORK/mxbuild" <<'MXB'
+#!/usr/bin/env bash
+ef=""; for a in "$@"; do case "$a" in --write-errors=*) ef="${a#--write-errors=}" ;; esac; done
+eval "m=\${$#}"; echo "$m" >> "$STUB_LOG/mxbuild-targets"
+[ -n "${STUB_MXB_TOUCH:-}" ] && echo "edited by someone else" >> "$STUB_MXB_TOUCH"
+if [ -n "${STUB_MXB_SP:-}" ]; then
+  nohup sleep 60 >/dev/null 2>&1 & echo $! >> "$STUB_LOG/sp-pids"
+  printf '{"ProcessId":%s}\n' "$!" > "$STUB_MXB_SP"
+fi
+if [ "${STUB_MXB_ERR:-0}" = 1 ]; then
+  printf '{"problems":[{"severity":"Error","errorCode":"CE0117","message":"Error(s) in expression.","locations":[{"module":"M","document":"D","element":"E"}]}]}' > "$ef"
+  exit 1
+fi
+printf '{"problems":[]}' > "$ef"; exit 0
+MXB
+chmod +x "$WORK/mxbuild"
+
+mkproj() {  # $1 = project dir, $2 = "" (root layout) or "app"
+  local P="$1" M="$1${2:+/$2}"
+  mkdir -p "$P/bin" "$P/mdlsource" "$M/mprcontents/ab" "$M/javasource/m"
+  printf 'model index v1\n' > "$M/Fixture.mpr"
+  printf 'unit a\n' > "$M/mprcontents/ab/a.mxunit"
+  printf 'unit b\n' > "$M/mprcontents/ab/b.mxunit"
+  printf 'class Old {}\n' > "$M/javasource/m/Old.java"
+  printf 'CREATE MODULE "Nope";\n' > "$P/mdlsource/test.mdl"
+  printf 'print("patched")\n' > "$P/mdlsource/p.sh"
+  cp "$TOOLKIT/project-bin/_common.sh" "$TOOLKIT/project-bin/restore-mpr.sh" "$TOOLKIT/project-bin/snapshot-mpr.sh" "$P/bin/"
+  cp "$SUBJECT" "$P/bin/exec.sh"
+  # mxcli: `exec <script> -p <mpr>` writes into the model it is given. STUB_EXEC_RC=1 writes half
+  # and fails; STUB_SIDE=1 also writes a Java file beside the model.
+  cat > "$P/mxcli" <<'MXCLI'
+#!/usr/bin/env bash
+[ "${1:-}" = exec ] || exit 0
+m=""; while [ $# -gt 0 ]; do [ "$1" = -p ] && m="$2"; shift; done
+echo "$m" >> "$STUB_LOG/exec-targets"
+d="$(dirname "$m")"
+echo "changed by exec" >> "$m"
+echo "changed by exec" >> "$d/mprcontents/ab/a.mxunit"
+[ "${STUB_EXEC_RC:-0}" = 1 ] && { echo "fake mxcli exec: statement 2 failed"; exit 1; }
+mkdir -p "$d/mprcontents/cd"; echo "new unit" > "$d/mprcontents/cd/new.mxunit"
+[ "${STUB_SIDE:-0}" = 1 ] && echo "class New {}" > "$d/javasource/m/New.java"
+echo "fake mxcli exec ok"; exit 0
+MXCLI
+  chmod +x "$P/bin/"*.sh "$P/mxcli"
+  ( cd "$P" && git init -q . && printf '.mpr-snapshots/\ndocs/\n.claude/\n' > .gitignore && git add -A \
+    && git -c user.email=t@t -c user.name=t commit -qm fixture ) >/dev/null 2>&1
+}
+fp() {  # $1 = model dir: every file of the live model tree (bytes and names), minus the logs exec.sh writes
+  ( cd "$1" && find . \( -path ./deployment -o -path ./.git -o -path ./.mpr-snapshots -o -path ./docs -o -path ./.claude \) -prune \
+      -o -type f ! -name '*.lock' -print | LC_ALL=C sort | while IFS= read -r f; do cksum "$f"; done ) | cksum
+}
+run() {  # $1 = project, rest = exec.sh args (env passes through)
+  local P="$1"; shift
+  mkdir -p "$WORK/log"; rm -f "$WORK/log/"*
+  ( cd "$P" && STUB_LOG="$WORK/log" JAVA_HOME="$WORK/jdk" SKIP_BASELINE=1 SP_RESTART=0 MXTK_NO_INSTALL=1 \
+      MXTK_NO_SCORE=1 SKIP_DOCTOR=1 MXBUILD_PATH="$WORK/mxbuild" ./bin/exec.sh "$@" ) 2>&1
+}
+rows() { grep -c '^| 20' "$1/docs/BUILD-LOG.md" 2>/dev/null || echo 0; }
+
+for LAYOUT in root app; do
+  SUB=""; [ "$LAYOUT" = app ] && SUB="app"
+  echo "== layout: $LAYOUT"
+
+  echo "-- flag unset: exec runs on the live model, as before"
+  P="$WORK/$LAYOUT-default"; mkproj "$P" "$SUB"; M="$P${SUB:+/$SUB}"
+  OUT="$(run "$P" mdlsource/test.mdl)"; RC=$?
+  [ "$RC" -eq 0 ] && ok "default run rc 0" || bad "default run rc $RC: $(printf '%s' "$OUT" | tail -4)"
+  [ "$(cat "$WORK/log/exec-targets" 2>/dev/null)" = "$M/Fixture.mpr" ] && ok "default: exec got the live .mpr" || bad "default: exec target $(cat "$WORK/log/exec-targets" 2>/dev/null)"
+  hasnt "default: no on-copy wording" "$OUT" "on-copy"
+  [ -d "$P/.mpr-snapshots/.on-copy" ] && bad "default: an on-copy dir was created" || ok "default: no scratch copy made"
+
+  echo "-- --on-copy, clean gate: promoted"
+  P="$WORK/$LAYOUT-clean"; mkproj "$P" "$SUB"; M="$P${SUB:+/$SUB}"
+  OUT="$(STUB_SIDE=1 run "$P" --on-copy mdlsource/test.mdl)"; RC=$?
+  [ "$RC" -eq 0 ] && ok "clean on-copy rc 0" || bad "clean on-copy rc $RC: $(printf '%s' "$OUT" | tail -6)"
+  case "$(cat "$WORK/log/exec-targets" 2>/dev/null)" in
+    "$P/.mpr-snapshots/.on-copy/"*/model/Fixture.mpr) ok "exec ran on the copy" ;;
+    *) bad "exec target: $(cat "$WORK/log/exec-targets" 2>/dev/null)" ;; esac
+  case "$(cat "$WORK/log/mxbuild-targets" 2>/dev/null)" in
+    "$P/.mpr-snapshots/.on-copy/"*/model/Fixture.mpr) ok "the mxbuild gate ran on the copy" ;;
+    *) bad "mxbuild target: $(cat "$WORK/log/mxbuild-targets" 2>/dev/null)" ;; esac
+  grep -q 'changed by exec' "$M/Fixture.mpr" && ok "live .mpr holds the change" || bad "live .mpr unchanged"
+  grep -q 'changed by exec' "$M/mprcontents/ab/a.mxunit" && ok "live unit holds the change" || bad "live unit unchanged"
+  [ -f "$M/mprcontents/cd/new.mxunit" ] && ok "new unit promoted" || bad "new unit missing"
+  [ -f "$M/javasource/m/New.java" ] && ok "file exec wrote outside the model promoted" || bad "javasource/m/New.java not promoted"
+  [ -f "$M/javasource/m/Old.java" ] && ok "untouched file outside the model still there" || bad "Old.java lost"
+  [ -z "$(ls -d "$M"/.mxtk-promote.* 2>/dev/null)" ] && ok "no promotion leftovers" || bad "leftovers: $(ls -d "$M"/.mxtk-promote.*)"
+  [ -z "$(ls -A "$P/.mpr-snapshots/.on-copy" 2>/dev/null)" ] && ok "scratch copy removed after promotion" || bad "scratch copy left: $(ls "$P/.mpr-snapshots/.on-copy")"
+  [ "$(rows "$P")" = 1 ] && ok "exactly one BUILD-LOG row" || bad "BUILD-LOG rows: $(rows "$P")"
+  has "row says applied + promoted" "$(cat "$P/docs/BUILD-LOG.md")" "on-copy: promoted"
+  has "row is an applied row" "$(cat "$P/docs/BUILD-LOG.md")" "✅ applied"
+  ls -d "$P/.mpr-snapshots/"[0-9]*/ >/dev/null 2>&1 && ok "pre-exec snapshot still taken" || bad "no snapshot"
+
+  echo "-- --on-copy, failing gate: live model untouched, copy kept"
+  P="$WORK/$LAYOUT-fail"; mkproj "$P" "$SUB"; M="$P${SUB:+/$SUB}"
+  B="$(fp "$M")"
+  OUT="$(STUB_MXB_ERR=1 run "$P" --on-copy mdlsource/test.mdl)"; RC=$?
+  [ "$RC" -ne 0 ] && ok "failing gate rc $RC" || bad "failing gate rc 0"
+  [ "$(fp "$M")" = "$B" ] && ok "live model byte-identical" || bad "live model changed after a failed on-copy exec"
+  K="$(ls -d "$P/.mpr-snapshots/.on-copy/"*/ 2>/dev/null | head -1)"
+  [ -n "$K" ] && grep -q 'changed by exec' "$K/model/Fixture.mpr" && ok "copy kept, holding the change" || bad "copy not kept"
+  has "prints the kept copy" "$OUT" "The copy is kept:"
+  has "prints a resume hint" "$OUT" "Resume: fix the script"
+  has "names statement-level resume as not built" "$OUT" "not built"
+  has "says the live model was never written" "$OUT" "never written"
+  [ "$(rows "$P")" = 1 ] && ok "exactly one BUILD-LOG row" || bad "BUILD-LOG rows: $(rows "$P")"
+  has "row says gate failed, on-copy" "$(cat "$P/docs/BUILD-LOG.md")" "live model not written"
+
+  echo "-- --on-copy, mxcli exec exit 1: partial on the copy only"
+  P="$WORK/$LAYOUT-partial"; mkproj "$P" "$SUB"; M="$P${SUB:+/$SUB}"
+  B="$(fp "$M")"
+  OUT="$(STUB_EXEC_RC=1 run "$P" --on-copy mdlsource/test.mdl)"; RC=$?
+  [ "$RC" -eq 1 ] && ok "exit code passed through (1)" || bad "rc $RC"
+  [ "$(fp "$M")" = "$B" ] && ok "live model byte-identical" || bad "live model changed after a partial on-copy exec"
+  has "says COPY, not the live model" "$OUT" "COPY (not the live model)"
+  [ "$(rows "$P")" = 1 ] && ok "exactly one BUILD-LOG row" || bad "BUILD-LOG rows: $(rows "$P")"
+  has "row says not promoted" "$(cat "$P/docs/BUILD-LOG.md")" "not promoted"
+
+  echo "-- live model modified during the exec: promotion refused"
+  P="$WORK/$LAYOUT-raced"; mkproj "$P" "$SUB"; M="$P${SUB:+/$SUB}"
+  OUT="$(STUB_MXB_TOUCH="$M/mprcontents/ab/b.mxunit" run "$P" --on-copy mdlsource/test.mdl)"; RC=$?
+  [ "$RC" -eq 1 ] && ok "refused rc 1" || bad "rc $RC: $(printf '%s' "$OUT" | tail -4)"
+  has "names why" "$OUT" "changed since the copy was taken"
+  grep -q 'edited by someone else' "$M/mprcontents/ab/b.mxunit" && ok "the concurrent change survives" || bad "concurrent change lost"
+  grep -q 'changed by exec' "$M/Fixture.mpr" && bad "exec's change was promoted over it" || ok "exec's change not promoted"
+  [ ! -f "$M/mprcontents/cd/new.mxunit" ] && ok "no new unit in live" || bad "new unit leaked into live"
+  [ -z "$(ls -d "$M"/.mxtk-promote.* 2>/dev/null)" ] && ok "staging cleaned up" || bad "staging left: $(ls -d "$M"/.mxtk-promote.*)"
+  K="$(ls -d "$P/.mpr-snapshots/.on-copy/"*/ 2>/dev/null | head -1)"
+  [ -n "$K" ] && [ -f "$K/model/Fixture.mpr" ] && [ -f "$K/model/mprcontents/cd/new.mxunit" ] && ok "copy kept whole (staged files put back)" || bad "copy incomplete after refusal"
+  has "row says not promoted" "$(cat "$P/docs/BUILD-LOG.md")" "🚫 not promoted"
+
+  echo "-- Studio Pro opens the project during the exec: promotion refused"
+  P="$WORK/$LAYOUT-sp"; mkproj "$P" "$SUB"; M="$P${SUB:+/$SUB}"
+  B="$(fp "$M")"
+  OUT="$(STUB_MXB_SP="$M/Fixture.mpr.lock" run "$P" --on-copy mdlsource/test.mdl)"; RC=$?
+  for p in $(cat "$WORK/log/sp-pids" 2>/dev/null); do BG="$BG $p"; done
+  [ "$RC" -eq 1 ] && ok "refused rc 1" || bad "rc $RC: $(printf '%s' "$OUT" | tail -4)"
+  has "names Studio Pro" "$OUT" "Studio Pro holds Fixture"
+  [ "$(fp "$M")" = "$B" ] && ok "live model byte-identical" || bad "live model changed while SP held it"
+
+  echo "-- swap fails half-way: renamed back"
+  P="$WORK/$LAYOUT-swapfail"; mkproj "$P" "$SUB"; M="$P${SUB:+/$SUB}"
+  B="$(fp "$M")"
+  OUT="$(_MXTK_TEST_SWAP_FAIL=mpr run "$P" --on-copy mdlsource/test.mdl)"; RC=$?
+  [ "$RC" -eq 1 ] && ok "rc 1" || bad "rc $RC"
+  has "says renamed back" "$OUT" "renamed back"
+  [ "$(fp "$M")" = "$B" ] && ok "live model byte-identical after the failed swap" || bad "live model differs after a failed swap"
+  [ -z "$(ls -d "$M"/.mxtk-promote.* 2>/dev/null)" ] && ok "no leftovers" || bad "leftovers: $(ls -d "$M"/.mxtk-promote.*)"
+  has "row says promotion failed" "$(cat "$P/docs/BUILD-LOG.md")" "promotion failed"
+done
+
+echo "== env and options"
+echo "-- EXEC_ON_COPY=1 is the same as --on-copy"
+P="$WORK/env"; mkproj "$P" ""
+OUT="$(EXEC_ON_COPY=1 run "$P" mdlsource/test.mdl)"; RC=$?
+case "$(cat "$WORK/log/exec-targets" 2>/dev/null)" in */.on-copy/*) ok "EXEC_ON_COPY=1 ran on a copy" ;; *) bad "EXEC_ON_COPY=1 target: $(cat "$WORK/log/exec-targets")" ;; esac
+[ "$RC" -eq 0 ] && grep -q 'changed by exec' "$P/Fixture.mpr" && ok "and promoted" || bad "not promoted (rc $RC)"
+
+echo "-- kept copies pruned to MXTK_ON_COPY_KEEP"
+P="$WORK/keep"; mkproj "$P" ""
+for i in 1 2 3 4; do STUB_MXB_ERR=1 run "$P" --on-copy mdlsource/test.mdl >/dev/null; sleep 1; done
+N="$(ls -d "$P/.mpr-snapshots/.on-copy/"*/ 2>/dev/null | wc -l | tr -d ' ')"
+[ "$N" = 3 ] && ok "4 failures keep the newest 3" || bad "kept $N copies"
+MXTK_ON_COPY_KEEP=1 STUB_MXB_ERR=1 run "$P" --on-copy mdlsource/test.mdl >/dev/null
+N="$(ls -d "$P/.mpr-snapshots/.on-copy/"*/ 2>/dev/null | wc -l | tr -d ' ')"
+[ "$N" = 1 ] && ok "MXTK_ON_COPY_KEEP=1 keeps 1" || bad "kept $N copies"
+N="$(ls -d "$P/.mpr-snapshots/"[0-9]*/ 2>/dev/null | wc -l | tr -d ' ')"
+[ "$N" -le 5 ] && ok "snapshot rotation unaffected by .on-copy ($N kept)" || bad "$N snapshots"
+
+echo "-- --on-copy --patch refused; EXEC_ON_COPY=1 --patch runs as before"
+P="$WORK/patch"; mkproj "$P" ""
+OUT="$(run "$P" --on-copy --patch mdlsource/p.sh)"; RC=$?
+[ "$RC" -eq 2 ] && ok "--on-copy --patch refused rc 2" || bad "rc $RC"
+has "and says so" "$OUT" "does not take --patch"
+printf '#!/bin/sh\necho patched >> "$1"\n' > "$P/mdlsource/p.sh"
+OUT="$(EXEC_ON_COPY=1 run "$P" --patch mdlsource/p.sh)"; RC=$?
+has "EXEC_ON_COPY with --patch: note" "$OUT" "does not apply to --patch"
+grep -q patched "$P/Fixture.mpr" && ok "patch ran on the live model" || bad "patch did not run (rc $RC): $(printf '%s' "$OUT" | tail -4)"
+
+echo "-- leftovers of an interrupted promotion refuse"
+P="$WORK/left"; mkproj "$P" ""
+mkdir "$P/.mxtk-promote.999.mprcontents"
+OUT="$(run "$P" --on-copy mdlsource/test.mdl)"; RC=$?
+[ "$RC" -eq 1 ] && ok "refused rc 1" || bad "rc $RC"
+has "names restore-mpr" "$OUT" "restore-mpr.sh"
+[ ! -f "$WORK/log/exec-targets" ] && ok "nothing executed" || bad "exec ran"
+
+echo ""
+echo "== $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ]

From 8ddb0cba5cd425009a3edb33a90c9f311f64e7b8 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 14 Oct 2026 16:17:12 +0000
Subject: [PATCH 2/7] =?UTF-8?q?fix(exec):=20#384=20review=20=E2=80=94=20le?=
 =?UTF-8?q?ftover=20guard=20on=20every=20path,=20precise=20recovery,=20sid?=
 =?UTF-8?q?e-file=20checks?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- M1: an interrupted --on-copy promotion (.mxtk-promote.* beside the model) now
  refuses every exec.sh path (default included) and test-scratch.sh's copy.
- M2: mxtk_promote_leftovers (_common.sh) reads a per-promotion manifest and
  prints the exact renames that put the live model back (or, for staged-only
  leftovers, says the live model is intact and to delete them); restore-mpr.sh
  only as the last resort, saying it drops later changes. Side-file leftovers
  (<rel>.mxtk-promote.N[.old]) included.
- M3: side files the promotion would replace are checked against their live
  checksum taken before the copy; a change refuses the promotion. Writes
  outside OC_SIDE_DIRS refuse too.
- L1: a part-way rollback hands every new file back to the copy, so the kept
  copy stays usable; the hint says so when it cannot.
- L2: <mpr>-wal/-shm/-journal never count as side files; live -wal is in the
  fingerprint and a non-empty -wal (live or copy) refuses the promotion.
- L4: single-tree checkouts copy an allow-list (the .mpr + MXTK_APP_DIRS).
- L5: test-scratch.sh refuses with a sync remedy when _common.sh lacks the
  copy routine.
- Nit: --on-copy with Studio Pro open refuses up front even under FORCE_EXEC.

Fixture test-exec-on-copy.sh: 176 checks, both layouts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 CHANGELOG.md                     |   2 +-
 project-bin/_common.sh           |  97 +++++++++++++--
 project-bin/exec.sh              | 197 +++++++++++++++++++++++--------
 project-bin/test-scratch.sh      |  16 ++-
 skills/iterative-build-loop.md   |   2 +-
 tests/wave2/test-exec-on-copy.sh |  92 ++++++++++++++-
 6 files changed, 339 insertions(+), 67 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d1f31fb9..33675d29 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,7 +19,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are. Named m
 
 ## Unreleased
 
-- new(exec): **`exec.sh --on-copy` (or `EXEC_ON_COPY=1`), opt-in: the script and the mxbuild gate run on a scratch copy, and the live model is written only by a rename-based promotion after a verified pass** ([#350](https://github.com/MendixMau/mxcli-project-toolkit/issues/350)). By default the live model holds an unverified write for the length of the gate (22-65 s per apply in the field), and keeps it when exec.sh is killed. Promotion is refused while Studio Pro holds the model (even under `FORCE_EXEC`), when the live model changed since the copy (cksum manifest), or when the copy is on another filesystem. A swap that fails part-way renames back, else restores the snapshot. On any other outcome the live model is untouched and the copy is kept under `.mpr-snapshots/.on-copy/` with a resume hint (newest 3 kept). Files exec writes outside the model (javasource/) are promoted with it. The default path is unchanged. The copy routine moved from `test-scratch.sh` into `_common.sh` (`mxtk_copy_model_tree`). Fixture `tests/wave2/test-exec-on-copy.sh` (108 checks, both layouts; 71 fail on master). Bench `tests/wave2/bench-exec-on-copy.sh` (stub mxbuild 2 s, an input): with exec.sh killed mid-gate the live model stayed byte-identical in 0/10 default runs and 10/10 on-copy runs at 500, 5,000 and 20,000 units. The broken window fell from about 2.1 s (clean) and 5.5-25.4 s (failed gate) to a 15-42 ms swap, at a cost of +1.4 s, +3.7 s and +10.9 s wall time per exec. Field evidence: none yet (stub-only); a field run with Studio Pro closed and then open is owed before it can become the default. Statement-level resume from the kept copy is a follow-up. — external review (#350), MendixMau
+- new(exec): **`exec.sh --on-copy` (or `EXEC_ON_COPY=1`), opt-in: the script and the mxbuild gate run on a scratch copy, and the live model is written only by a rename-based promotion after a verified pass** ([#350](https://github.com/MendixMau/mxcli-project-toolkit/issues/350)). By default the live model holds an unverified write for the length of the gate (22-65 s per apply in the field), and keeps it when exec.sh is killed. Promotion is refused while Studio Pro holds the model (even under `FORCE_EXEC`), when the live model changed since the copy (cksum manifest), or when the copy is on another filesystem. A swap that fails part-way renames back, else restores the snapshot. On any other outcome the live model is untouched and the copy is kept under `.mpr-snapshots/.on-copy/` with a resume hint (newest 3 kept). Files exec writes beside the model (javasource/, javascriptsource/, theme/...) are promoted with it only if their live copy still matches its pre-copy checksum; a write anywhere else refuses. A single-tree checkout copies only the `.mpr` and the app directories, never sources/, analysis/, docs/ or binaries. A promotion killed half-way leaves `.mxtk-promote.*` names: every exec.sh path (the default one included) and `test-scratch.sh` then refuse and print the exact renames that put the live model back, with `restore-mpr.sh` only as the last resort. The default path is otherwise unchanged. The copy routine moved from `test-scratch.sh` into `_common.sh` (`mxtk_copy_model_tree`, `mxtk_promote_leftovers`). Fixture `tests/wave2/test-exec-on-copy.sh` (176 checks, both layouts). Bench `tests/wave2/bench-exec-on-copy.sh` (stub mxbuild 2 s, an input): with exec.sh killed mid-gate the live model stayed byte-identical in 0/10 default runs and 10/10 on-copy runs at 500, 5,000 and 20,000 units. The broken window fell from about 2.1 s (clean) and 5.5-25.4 s (failed gate) to a 15-42 ms swap, at a cost of +1.4 s, +3.7 s and +10.9 s wall time per exec. Field evidence: none yet (stub-only); a field run with Studio Pro closed and then open is owed before it can become the default. Statement-level resume from the kept copy is a follow-up. — external review (#350), MendixMau
 - process(build): **Stage 5 drafts the ready set in parallel and applies serially.** The runbook dispatch row said "sequential within a module", which serialised drafting even for independent scripts; it now points to `iterative-build-loop.md` → Gate cost, the single statement of the rule. The unit is the build-plan row: every `BUILD` row whose "Depends on" rows are all applied, minus overlapping writers (two rows that replace, alter or drop+create the same document never share a ready set, and no row is drafted while it overlaps a queued unapplied one; `brd-to-build-plan.md` has Produces name every document a row writes), runs at once, its scripts in order, one `mdl-agent` per script. Applies stay one at a time through `bin/exec.sh`, and the ready set is recomputed after each. A queued draft made before a sibling apply landed is re-checked with `mxcli diff --format struct` (preflight STOP rule 23); any removal line (checked against `describe` per BUG-146) or STOP rule 21 target means re-draft, never patch, because a stale restatement of a shared document is exactly rule 21's silent seed-call loss and passes `check --references`. Report `ready set N, drafted N, applied k`; the `mdl-agent` template says a drafter never applies and never depends on an unapplied draft. Field evidence: none yet. — MendixMau
 - fix(platform-link): **CLI commits now show their changed documents in Studio Pro History.** Studio Pro's History → Model changes pane reads a `ModelChanges` array from the commit's `refs/notes/mx_metadata` note. Trap 6c's hand-written template set it to `[]`, so every mxcli/agent commit showed "Model changes 0" (field project: 270 of 270 notes empty). New `project-bin/mx-metadata-note.py` (stdlib only) computes the array from the commit's changed `.mxunit` files, in Studio Pro's entry shape: Status, UnitID, UnitType, UnitName and Module (walked up the `.mpr` Unit tree). It has `changes` / `write` / `backfill` / `sync <remote>` subcommands. `install-project-hooks.sh` now also installs post-commit and post-rewrite hooks that write the note and never block, and `--check` covers them, so `sync-project.sh` rolls them out to wired projects. Notes are published with `mx-metadata-note.py sync <remote>` after the branch push. Push config is never touched. With mxcli v0.26+ in the project root the hooks call `mxcli git note --write` instead (mendixlabs/mxcli#1337); the Python script is the fallback for older pins, and on 160 field commits both wrote the same 3,594 entries. Trap 6c rewritten. Measured against Studio Pro's own notes, 51 commits in 5 apps: 3387/3389 entries exact on all five fields. Field run on a 357-commit Mendix 11.15.0 app: 158 notes backfilled and pushed, and Studio Pro History lists the documents per revision. Review fixes: an earlier revision added `HEAD` + the notes ref to `remote.<r>.push`. It was dropped because any push refspec replaces `push.default`. A branch tracking a differently named upstream got a new same-named branch on Team Server where `simple` refuses, a missing local notes ref failed the whole push, and nobody knows whether Studio Pro's own push reads that config. The installer now only fetches the remote's notes (non-forced). It removes that exact `HEAD` + notes pair if present, and leaves and reports any other entry. `sync` handles a remote with no notes ref (it used to exit 1) and retries a rejected push once after re-merging. A note that already lists changes (Studio Pro's) is never overwritten by `write`/`backfill` without `--force`, and `sync` keeps a colleague's non-empty note over ours. The mxcli probe greps `git note --help` for `--write`. Hooks and docs call the script through `resolve_py`. Fixture `tests/wave2/test-mx-metadata-note.sh` (40 cases, over real captured template units; single- and two-tree layouts, amend, backfill and `--force`, push exit codes identical to a no-hooks clone, leftover-refspec cleanup, sync to an empty remote and its retry, notes fetch at install, a diverged notes merge; green under `init.defaultBranch` master and main). — field project (Mendix 11.15 app), MendixMau
 - learn(fixture-seeding): **explore the data structure first, choose rows by use case, scan actions for resets before any run.** Two seeding runs on public template apps: seeding raised journey passes 33 -> 58 and 20 -> 51 of the same sets (FAIL 93 -> 68, 163 -> 132; INVALID unchanged), and a "Reset all demodata" journey wiped accounts so 104 of 127 journeys reported `The username or password you entered is incorrect`, identical on empty and seeded databases. Skill gains three questions a seed must answer, a use-case checklist, a destructive-action scan, a generic traps table with symptoms, measured expectations and a denominator checklist; routing trigger now fires on seed/test/demo data and empty pages. Independent review fixes: object ids follow the Mendix bigint pattern with a business-key guard (no uuids), associations are seeded where the page's path stores them, four new traps (enum names, inheritance chain, calculated attributes, view/external entities), and the port-offset and container-label traps moved to `harness-architecture.md`. — MendixMau
diff --git a/project-bin/_common.sh b/project-bin/_common.sh
index 27bbf05c..c5f46ded 100755
--- a/project-bin/_common.sh
+++ b/project-bin/_common.sh
@@ -642,18 +642,97 @@ mxtk_mxbuild_why() {
   "$_py" -c "import json;d=json.load(open('$(native_path "$1")'));print('; '.join((e.get('message','') if isinstance(e,dict) else str(e)) for e in d.get('errors',[]) or [])[:300])" 2>/dev/null || true
 }
 
-# mxtk_copy_model_tree <model-dir> <dest-dir> — copy the model tree (the .mpr, mprcontents/ and
-# everything mxbuild reads beside them: widgets/, javasource/, theme/, userlib/ ...) into an
-# existing <dest-dir>. Leaves out .git, .mpr-snapshots, deployment, .mxcli (the LIVE app's
-# run --local record — a copy carrying it points app-restart.sh at the live app) and node_modules.
-# One routine for both scratch-copy users: bin/test-scratch.sh (mxcli test, #278) and
-# bin/exec.sh --on-copy (#350). tar preserves mtimes, which --on-copy relies on to tell the
-# files `mxcli exec` wrote from the files it copied. Returns tar's status.
+# mxtk_copy_model_tree <model-dir> <dest-dir> [<mpr-basename>] — copy the model tree into an
+# existing <dest-dir>, for a scratch copy.
+#   Two args: the whole <model-dir> (the .mpr, mprcontents/ and everything mxbuild reads beside
+#   them), leaving out .git, .mpr-snapshots, deployment, .mxcli (the LIVE app's run --local record
+#   — a copy carrying it points app-restart.sh at the live app) and node_modules.
+#   Three args: an ALLOW-LIST — <mpr-basename> with its -wal/-shm if present, plus the app
+#   directories in $MXTK_APP_DIRS that exist. For a single-tree checkout, where <model-dir> is the
+#   repo root and also holds sources/, analysis/, docs/ and binaries nobody's build reads. A
+#   directory mxbuild needs and the list lacks makes the gate fail ON THE COPY — never the live
+#   model — and MXTK_APP_DIRS adds it.
+# Used by bin/test-scratch.sh (mxcli test, #278; two args) and bin/exec.sh --on-copy (#350). tar
+# preserves mtimes, which --on-copy relies on to tell the files `mxcli exec` wrote from the files
+# it copied. Returns tar's status.
+MXTK_APP_DIRS="${MXTK_APP_DIRS:-mprcontents widgets javasource javascriptsource theme themesource userlib vendorlib resources nativemobile}"
 mxtk_copy_model_tree() {
-  tar -C "$1" --exclude=./.git --exclude=./.mpr-snapshots --exclude=./deployment \
-      --exclude=./.mxcli --exclude=./node_modules -cf - . | tar -C "$2" -xf -
+  if [ -z "${3:-}" ]; then
+    tar -C "$1" --exclude=./.git --exclude=./.mpr-snapshots --exclude=./deployment \
+        --exclude=./.mxcli --exclude=./node_modules -cf - . | tar -C "$2" -xf -
+    return
+  fi
+  local _src="$1" _dst="$2" _mb="$3" _e
+  set --
+  for _e in "$_mb" "$_mb-wal" "$_mb-shm" $MXTK_APP_DIRS; do [ -e "$_src/$_e" ] && set -- "$@" "./$_e"; done
+  tar -C "$_src" --exclude=node_modules -cf - "$@" | tar -C "$_dst" -xf -
+}
+
+# mxtk_promote_leftovers <model-dir> <mpr-basename> — 0 (and a diagnosis on stdout) iff an
+# exec.sh --on-copy promotion was killed part-way and left its files beside the model. Every
+# model writer and copier calls this first (exec.sh on every path, test-scratch.sh): a kill
+# between the two mprcontents/ renames leaves NO mprcontents/, and a default exec would then
+# snapshot and write that (#384 review). Names, all under <model-dir>, for promotion PID N:
+#   .mxtk-promote.N.manifest        side files of that promotion, "E <rel>" (existed live) / "N <rel>"
+#   .mxtk-promote.N.mpr / .mprcontents   staged new model — never live yet
+#   .mxtk-promote.N.old.mpr / .old.mprcontents   the live model, moved aside by the swap
+#   <rel>.mxtk-promote.N            a staged side file;  <rel>.mxtk-promote.N.old  its live original
+# The printed commands put the pre-promotion live model back by rename — every rename the swap
+# did, undone — then remove the rest. Only the glob runs when there is nothing: cheap per exec.
+mxtk_promote_leftovers() {
+  local md="$1" mb="$2" f n pids="" p t cmds k rel any_old
+  for f in "$md"/.mxtk-promote.*; do
+    [ -e "$f" ] || continue
+    n="${f##*/.mxtk-promote.}"; n="${n%%.*}"
+    case " $pids " in *" $n "*) ;; *) pids="$pids $n" ;; esac
+  done
+  [ -n "$pids" ] || return 1
+  for p in $pids; do
+    t="$md/.mxtk-promote.$p"; cmds=""; any_old=0
+    if [ -d "$t.old.mprcontents" ]; then
+      any_old=1
+      [ -d "$md/mprcontents" ] && cmds="$cmds
+mv '$md/mprcontents' '$t.new.mprcontents'"
+      cmds="$cmds
+mv '$t.old.mprcontents' '$md/mprcontents'"
+    fi
+    # .old.mpr is a hard link taken before the swap; while it is still the live file (-ef), the
+    # .mpr was not replaced and the rm at the end is enough.
+    if [ -f "$t.old.mpr" ] && ! [ "$t.old.mpr" -ef "$md/$mb" ]; then
+      any_old=1; cmds="$cmds
+mv -f '$t.old.mpr' '$md/$mb'"
+    fi
+    if [ -f "$t.manifest" ]; then
+      while read -r k rel; do
+        [ -n "$rel" ] || continue
+        if [ -f "$md/$rel.mxtk-promote.$p.old" ]; then
+          any_old=1; cmds="$cmds
+mv -f '$md/$rel.mxtk-promote.$p.old' '$md/$rel'"
+        elif [ "$k" = N ] && [ ! -f "$md/$rel.mxtk-promote.$p" ] && [ -f "$md/$rel" ]; then
+          any_old=1; cmds="$cmds
+rm -f '$md/$rel'"   # created by the promotion; did not exist before it
+        fi
+        [ -f "$md/$rel.mxtk-promote.$p" ] && cmds="$cmds
+rm -f '$md/$rel.mxtk-promote.$p'"
+      done < "$t.manifest"
+    fi
+    cmds="$cmds
+rm -rf '$t'.*"
+    if [ "$any_old" = 1 ]; then
+      echo "✗ An exec.sh --on-copy promotion (PID $p) was interrupted part-way: the live model may be half-swapped."
+      echo "  Put the live model back as it was before that promotion, by rename (run these in order):"
+    else
+      echo "✗ An exec.sh --on-copy promotion (PID $p) was interrupted before it replaced anything: the live model is intact."
+      echo "  Only staged files are left. Remove them:"
+    fi
+    printf '%s\n' "$cmds" | grep . | sed 's/^/      /'
+  done
+  echo "  Then re-run. Last resort only: ./bin/restore-mpr.sh restores the newest snapshot (the model before"
+  echo "  that exec) and DROPS every model change made after that snapshot was taken."
+  return 0
 }
 
+
 # project_name — the .mpr basename without extension, for user-facing messages.
 project_name() {
   local mpr
diff --git a/project-bin/exec.sh b/project-bin/exec.sh
index f57c2859..67386f56 100755
--- a/project-bin/exec.sh
+++ b/project-bin/exec.sh
@@ -31,11 +31,16 @@
 # or when the copy is not on the model's filesystem (a rename would become a copy). The swap is
 # renames only: .mpr is replaced by one rename (atomic); mprcontents/ by two (live -> aside, new ->
 # live), so for the microseconds between them there is no mprcontents/ (rename(2) cannot exchange
-# two directories portably). Files `mxcli exec` wrote outside the model (javasource/ for a Java
-# action) are promoted the same way, one rename each; a file it DELETED there is not mirrored
-# (follow-up). A swap that fails half-way renames back, else restores the pre-exec snapshot. On any
-# other outcome the live model is never written and the copy is kept with a resume hint; the
-# newest MXTK_ON_COPY_KEEP (default 3) kept copies survive. Not with --patch (follow-up).
+# two directories portably). Files `mxcli exec` wrote beside the model under OC_SIDE_DIRS
+# (javasource/ for a Java action) are promoted the same way, one rename each, and only if the live
+# file still matches its pre-copy checksum; a write anywhere else refuses the promotion, and a file
+# exec DELETED is not mirrored (follow-up). A swap that fails half-way renames back (the copy is
+# handed back whole), else restores the pre-exec snapshot. A promotion KILLED half-way leaves
+# .mxtk-promote.* names that every exec.sh path and test-scratch.sh refuse on, printing the exact
+# renames that put the live model back (mxtk_promote_leftovers, _common.sh). On a single-tree
+# checkout only the .mpr and the app directories (MXTK_APP_DIRS) are copied, never sources/,
+# analysis/, docs/ or binaries. On any other outcome the live model is never written and the copy is
+# kept with a resume hint; the newest MXTK_ON_COPY_KEEP (default 3) survive. Not with --patch.
 #
 # --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
@@ -539,6 +544,10 @@ if sp_holds_model; then
   SP_OPEN=1
   echo "✗ Studio Pro has $NAME open (lock PID $SP_PID alive) — refusing exec (split-brain corruption risk)."
   echo "  → Close the project in Studio Pro (or quit SP), then re-run."
+  if [ "$ON_COPY" = 1 ]; then
+    echo "    --on-copy: FORCE_EXEC does not override this — a promotion is refused while Studio Pro holds the model."
+    exit 1
+  fi
   echo "    Override (NOT recommended): FORCE_EXEC=1 ./bin/exec.sh $SCRIPT"
   [ "$FORCE" = "1" ] || exit 1
   echo "  (FORCE_EXEC set — proceeding despite open SP)"
@@ -652,6 +661,17 @@ if command -v pgrep >/dev/null 2>&1; then
   [ -n "$_raw" ] && echo "  note: an 'mxcli exec' is running elsewhere on this machine (PID ${_raw% }) — not blocking; only another exec.sh on this project is."
 fi
 
+# 3b. An exec.sh --on-copy promotion killed part-way (#350, #384 review) leaves .mxtk-promote.*
+#    beside the model, and between its two renames NO mprcontents/. Every path refuses until it is
+#    put back, so a default exec never snapshots and writes a half-swapped model. The diagnosis and
+#    the exact rename commands come from mxtk_promote_leftovers (_common.sh); the check is one glob.
+if type mxtk_promote_leftovers >/dev/null 2>&1 && _oc_left="$(mxtk_promote_leftovers "$MODEL_DIR" "$MPR_BASE")"; then
+  printf '%s\n' "$_oc_left"
+  echo "  Nothing was snapshotted or executed."
+  log_build "🚫 blocked" "interrupted --on-copy promotion left .mxtk-promote.* beside the model"
+  exit 1
+fi
+
 # 4. Uncommitted model changes. The snapshot taken below would not cover them,
 #    so a failed gate would auto-restore to a state pre-dating those changes and
 #    silently lose work. --commit-first (opt-in) commits exactly the model paths first.
@@ -998,23 +1018,40 @@ fi
 OC_ROOT="$PROJECT_ROOT/.mpr-snapshots/.on-copy"   # hidden: snapshot rotation (ls */) never sees it
 OC_KEEP="${MXTK_ON_COPY_KEEP:-3}"
 case "$OC_KEEP" in ''|*[!0-9]*|0) OC_KEEP=3 ;; esac
-OC_SCR=""; OC_COPY=""; OC_MPR=""; OC_FP0=""; OC_SIDE=""; OC_WHY=""; OC_LIVE_WRITTEN=0
-OC_COPY_MS=0; OC_SWAP_MS=0; OC_UNITS=0
+# Directories where a file `mxcli exec` writes beside the model is promoted with it (a Java or
+# JavaScript action, a theme file). A write anywhere else outside the model refuses the promotion.
+OC_SIDE_DIRS="javasource javascriptsource theme themesource resources nativemobile"
+OC_SCR=""; OC_COPY=""; OC_MPR=""; OC_FP0=""; OC_SIDE0=""; OC_SIDE=""; OC_SIDE_OTHER=""; OC_WHY=""
+OC_LIVE_WRITTEN=0; OC_COPY_MS=0; OC_SWAP_MS=0; OC_UNITS=0
 TARGET_MPR="$MPR"
 oc_ms() {  # wall clock in ms (GNU date); whole seconds x1000 where %N is not supported (BSD)
   _n="$(date +%s%N 2>/dev/null)"
   case "$_n" in ''|*[!0-9]*) echo $(( $(date +%s) * 1000 )) ;; *) echo $(( _n / 1000000 )) ;; esac
 }
-oc_fingerprint() {  # $1 = model dir. One cksum over the .mpr and every mprcontents/ file (name + bytes)
-  ( cd "$1" && { cksum "$MPR_BASE"
+oc_fingerprint() {  # $1 = model dir. One cksum over the .mpr, its -wal, and every mprcontents/ file
+  ( cd "$1" && { cksum "$MPR_BASE"; [ -f "$MPR_BASE-wal" ] && cksum "$MPR_BASE-wal"
       if [ -d mprcontents ]; then find mprcontents -type f | LC_ALL=C sort | tr '\n' '\0' | xargs -0 cksum; fi; } ) 2>/dev/null | cksum
 }
+oc_side_manifest() {  # $1 = model dir: "crc size path" per file under $OC_SIDE_DIRS
+  ( cd "$1" && for _d in $OC_SIDE_DIRS; do [ -d "$_d" ] && find "$_d" -type f; done | LC_ALL=C sort \
+      | while IFS= read -r _f; do cksum "$_f"; done ) 2>/dev/null
+}
+oc_side_sum() {  # $1 = file: "crc size", or "-" when it does not exist
+  if [ -f "$1" ]; then cksum < "$1" | awk '{print $1, $2}'; else echo "-"; fi
+}
+oc_side_sum0() {  # $1 = rel path: its "crc size" in OC_SIDE0 (taken before the copy), or "-"
+  printf '%s\n' "$OC_SIDE0" | awk -v r="$1" '{ c = $1; s = $2; p = $0; sub(/^[^ ]+ [^ ]+ /, "", p); if (p == r) { print c, s; f = 1; exit } } END { if (!f) print "-" }'
+}
 oc_prune() {  # keep the newest $OC_KEEP kept copies
-  ls -dt "$OC_ROOT"/*/ 2>/dev/null | tail -n +$((OC_KEEP + 1)) | while read -r _d; do rm -rf "$_d"; done
+  ls -dt "$OC_ROOT"/*/ 2>/dev/null | tail -n +$((OC_KEEP + 1)) | while read -r _d; do rm -rf "${_d:?}"; done
 }
 oc_keep_hint() {
-  echo "  The copy is kept: $OC_COPY"
-  echo "    It holds what the script did. Look at it: ./mxcli -p $OC_MPR -c \"SHOW STRUCTURE\""
+  if [ -f "$OC_MPR" ]; then
+    echo "  The copy is kept: $OC_COPY"
+    echo "    It holds what the script did. Look at it: ./mxcli -p $OC_MPR -c \"SHOW STRUCTURE\""
+  else
+    echo "  The copy at $OC_COPY is incomplete (the failed swap could not hand all of it back); it is kept for inspection only."
+  fi
   echo "  Resume: fix the script and re-run ./bin/exec.sh --on-copy $SCRIPT — it starts from a fresh copy"
   echo "    of the live model. Resuming THIS copy with only the statements that did not land is not built"
   echo "    yet (toolkit #350 follow-up)."
@@ -1022,63 +1059,91 @@ oc_keep_hint() {
   echo "  The newest $OC_KEEP kept copies stay under .mpr-snapshots/.on-copy/ (MXTK_ON_COPY_KEEP); older ones were removed."
 }
 oc_unstage() {  # put staged files back into the copy (nothing in the live model was replaced yet)
-  _t="$1"
   [ -f "$MODEL_DIR/$_t.mpr" ] && mv "$MODEL_DIR/$_t.mpr" "$OC_COPY/$MPR_BASE" 2>/dev/null
   [ -d "$MODEL_DIR/$_t.mprcontents" ] && mv "$MODEL_DIR/$_t.mprcontents" "$OC_COPY/mprcontents" 2>/dev/null
   printf '%s\n' "$OC_SIDE" | while IFS= read -r _r; do
-    [ -n "$_r" ] && [ -f "$MODEL_DIR/$_r.$_t" ] && mv "$MODEL_DIR/$_r.$_t" "$OC_COPY/$_r" 2>/dev/null
+    [ -n "$_r" ] && [ -f "$MODEL_DIR/$_r.$_st" ] && mv "$MODEL_DIR/$_r.$_st" "$OC_COPY/$_r" 2>/dev/null
   done
+  rm -f "${MODEL_DIR:?}/${_t:?}.manifest" "${MODEL_DIR:?}/${_t:?}.old.mpr"
   return 0
 }
 # oc_promote — 0 promoted · 1 refused, the live model untouched · 2 the swap failed part-way
 # (rolled back by rename, else restored from the pre-exec snapshot; OC_WHY says which).
+# Every name it leaves beside the model is one mxtk_promote_leftovers (_common.sh) can read back,
+# so a promotion killed at any point is recoverable by rename on the next run.
 oc_promote() {
-  _md="$MODEL_DIR"; _t=".mxtk-promote.$$"; _step=""
+  _md="$MODEL_DIR"; _t=".mxtk-promote.$$"; _st="mxtk-promote.$$"; _step=""
   OC_WHY=""
   if sp_holds_model; then
     OC_WHY="Studio Pro holds $NAME (lock PID $SP_PID); its in-memory model would overwrite the promotion on its next save"; return 1
   fi
+  if [ -n "$OC_SIDE_OTHER" ]; then
+    OC_WHY="mxcli exec also wrote outside the model and outside $OC_SIDE_DIRS: $(printf '%s' "$OC_SIDE_OTHER" | head -3 | tr '\n' ' ')— not promoted blind"; return 1
+  fi
+  if [ -s "$OC_COPY/$MPR_BASE-wal" ]; then
+    OC_WHY="the copy's $MPR_BASE-wal is not empty (SQLite did not checkpoint it); the .mpr alone is not the whole model"; return 1
+  fi
+  if [ -s "$_md/$MPR_BASE-wal" ]; then
+    OC_WHY="the live $MPR_BASE-wal is not empty — something holds the model open, or it was not closed cleanly"; return 1
+  fi
   # A rename across filesystems is a copy. ln (a hard link) fails across filesystems, on every platform.
   : > "$OC_SCR/.fsprobe"
   if ! ln "$OC_SCR/.fsprobe" "$_md/$_t.fsprobe" 2>/dev/null; then
-    rm -f "$OC_SCR/.fsprobe"
+    rm -f "${OC_SCR:?}/.fsprobe"
     OC_WHY="the copy is not on the model's filesystem, so the swap could not be a rename"; return 1
   fi
-  rm -f "$OC_SCR/.fsprobe" "$_md/$_t.fsprobe"
+  rm -f "${OC_SCR:?}/.fsprobe" "${_md:?}/${_t:?}.fsprobe"
+  # Side files exec will promote that exist live must still be what was copied (#384 M3).
+  _changed=""
+  while IFS= read -r _r; do
+    [ -n "$_r" ] || continue
+    [ "$(oc_side_sum "$_md/$_r")" = "$(oc_side_sum0 "$_r")" ] || _changed="$_changed $_r"
+  done <<OCSIDE
+$OC_SIDE
+OCSIDE
+  if [ -n "$_changed" ]; then
+    OC_WHY="a file the promotion would replace changed live since the copy was taken:$_changed"; return 1
+  fi
+  # The manifest first, so a kill from here on leaves something mxtk_promote_leftovers can read.
+  printf '%s\n' "$OC_SIDE" | while IFS= read -r _r; do
+    [ -n "$_r" ] || continue
+    if [ -f "$_md/$_r" ]; then echo "E $_r"; else echo "N $_r"; fi
+  done > "$_md/$_t.manifest"
   # Stage beside the live files (renames). Nothing live is replaced yet.
   OC_UNITS=0
   [ -d "$OC_COPY/mprcontents" ] && OC_UNITS=$(find "$OC_COPY/mprcontents" -type f | wc -l | tr -d ' ')
   if ! mv "$OC_COPY/$MPR_BASE" "$_md/$_t.mpr" \
      || { [ -d "$OC_COPY/mprcontents" ] && ! mv "$OC_COPY/mprcontents" "$_md/$_t.mprcontents"; }; then
-    oc_unstage "$_t"; OC_WHY="staging the copy beside the live model failed"; return 1
+    oc_unstage; OC_WHY="staging the copy beside the live model failed"; return 1
   fi
   _sidefail=0
   while IFS= read -r _r; do
     [ -n "$_r" ] || continue
-    mkdir -p "$_md/$(dirname "$_r")" && mv "$OC_COPY/$_r" "$_md/$_r.$_t" || { _sidefail=1; break; }
+    mkdir -p "$_md/$(dirname "$_r")" && mv "$OC_COPY/$_r" "$_md/$_r.$_st" || { _sidefail=1; break; }
   done <<OCSIDE
 $OC_SIDE
 OCSIDE
-  if [ "$_sidefail" = 1 ]; then oc_unstage "$_t"; OC_WHY="staging a file mxcli exec wrote outside the model failed"; return 1; fi
+  if [ "$_sidefail" = 1 ]; then oc_unstage; OC_WHY="staging a file mxcli exec wrote outside the model failed"; return 1; fi
   # Last checks, right before the swap: the live model is what was copied, and SP is still closed.
   if [ "$(oc_fingerprint "$_md")" != "$OC_FP0" ]; then
-    oc_unstage "$_t"
+    oc_unstage
     OC_WHY="the live model changed since the copy was taken (Studio Pro save, git checkout, another writer); promoting would drop that change"; return 1
   fi
   if sp_holds_model; then
-    oc_unstage "$_t"; OC_WHY="Studio Pro opened $NAME (lock PID $SP_PID) during the exec"; return 1
+    oc_unstage; OC_WHY="Studio Pro opened $NAME (lock PID $SP_PID) during the exec"; return 1
   fi
   # The swap: renames only. Old files stay beside the new ones until the swap is verified.
   _s0=$(oc_ms); OC_LIVE_WRITTEN=1
-  { ln "$_md/$MPR_BASE" "$_md/$_t.old.mpr" 2>/dev/null || cp -p "$_md/$MPR_BASE" "$_md/$_t.old.mpr"; } || { oc_unstage "$_t"; OC_LIVE_WRITTEN=0; OC_WHY="could not keep the old .mpr aside"; return 1; }
+  { ln "$_md/$MPR_BASE" "$_md/$_t.old.mpr" 2>/dev/null || cp -p "$_md/$MPR_BASE" "$_md/$_t.old.mpr"; } || { oc_unstage; OC_LIVE_WRITTEN=0; OC_WHY="could not keep the old .mpr aside"; return 1; }
   _ok=1
   if [ -d "$_md/mprcontents" ]; then
     if mv "$_md/mprcontents" "$_md/$_t.old.mprcontents"; then _step="aside"; else _ok=0; fi
   fi
+  if [ "${_MXTK_TEST_SWAP_KILL:-}" = mprcontents ]; then kill -KILL $$; fi   # fixture hook: killed between the two renames
   if [ "$_ok" = 1 ] && [ -d "$_md/$_t.mprcontents" ]; then
     if mv "$_md/$_t.mprcontents" "$_md/mprcontents"; then _step="$_step in"; else _ok=0; fi
   fi
-  [ "${_MXTK_TEST_SWAP_FAIL:-}" = mpr ] && _ok=0   # fixture hook: fail between the two halves
+  [ "${_MXTK_TEST_SWAP_FAIL:-}" = mpr ] && _ok=0   # fixture hook: fail before the .mpr rename
   if [ "$_ok" = 1 ]; then
     if mv -f "$_md/$_t.mpr" "$_md/$MPR_BASE"; then _step="$_step mpr"; else _ok=0; fi
   fi
@@ -1086,9 +1151,10 @@ OCSIDE
   if [ "$_ok" = 1 ]; then
     while IFS= read -r _r; do
       [ -n "$_r" ] || continue
-      [ -f "$_md/$_r" ] && { ln "$_md/$_r" "$_md/$_r.$_t.old" 2>/dev/null || cp -p "$_md/$_r" "$_md/$_r.$_t.old"; }
-      if mv -f "$_md/$_r.$_t" "$_md/$_r"; then _sides="$_sides
+      [ -f "$_md/$_r" ] && { ln "$_md/$_r" "$_md/$_r.$_st.old" 2>/dev/null || cp -p "$_md/$_r" "$_md/$_r.$_st.old"; }
+      if mv -f "$_md/$_r.$_st" "$_md/$_r"; then _sides="$_sides
 $_r"; else _ok=0; break; fi
+      if [ "${_MXTK_TEST_SWAP_KILL:-}" = side ]; then kill -KILL $$; fi   # fixture hook: killed after a side file
     done <<OCSIDE
 $OC_SIDE
 OCSIDE
@@ -1102,44 +1168,53 @@ OCSIDE
     OC_SWAP_MS=$(( _s1 - _s0 ))
     # Old files out of the model dir, into the scratch dir, then the scratch dir goes.
     [ -d "$_md/$_t.old.mprcontents" ] && mv "$_md/$_t.old.mprcontents" "$OC_SCR/old-mprcontents"
-    rm -f "$_md/$_t.old.mpr"
-    printf '%s\n' "$OC_SIDE" | while IFS= read -r _r; do [ -n "$_r" ] && rm -f "$_md/$_r.$_t.old"; done
+    rm -f "${_md:?}/${_t:?}.old.mpr"
+    printf '%s\n' "$OC_SIDE" | while IFS= read -r _r; do [ -n "$_r" ] && rm -f "${_md:?}/${_r:?}.${_st:?}.old"; done
+    rm -f "${_md:?}/${_t:?}.manifest"
     return 0
   fi
-  # Part-way failure: undo by rename, newest step first; anything that fails -> the snapshot.
+  # Part-way failure: undo by rename, newest step first, handing every new file back to the copy
+  # so the kept copy stays whole (#384 L1); anything that fails -> the snapshot.
   _back=1
   printf '%s\n' "$_sides" | while IFS= read -r _r; do
     [ -n "$_r" ] || continue
-    if [ -f "$_md/$_r.$_t.old" ]; then mv -f "$_md/$_r.$_t.old" "$_md/$_r"; else rm -f "$_md/$_r"; fi
+    mkdir -p "$OC_COPY/$(dirname "$_r")"; mv -f "$_md/$_r" "$OC_COPY/$_r"
+    [ -f "$_md/$_r.$_st.old" ] && mv -f "$_md/$_r.$_st.old" "$_md/$_r"
   done
-  case "$_step" in *mpr*) mv -f "$_md/$_t.old.mpr" "$_md/$MPR_BASE" || _back=0 ;; *) rm -f "$_md/$_t.old.mpr" ;; esac
-  case "$_step" in *in*) mv "$_md/mprcontents" "$OC_SCR/failed-mprcontents" || _back=0 ;; esac
+  printf '%s\n' "$OC_SIDE" | while IFS= read -r _r; do
+    [ -n "$_r" ] || continue
+    [ -f "$_md/$_r.$_st" ] && mv -f "$_md/$_r.$_st" "$OC_COPY/$_r"
+    rm -f "${_md:?}/${_r:?}.${_st:?}.old"
+  done
+  case "$_step" in
+    *mpr*) { ln "$_md/$MPR_BASE" "$OC_COPY/$MPR_BASE" 2>/dev/null || cp -p "$_md/$MPR_BASE" "$OC_COPY/$MPR_BASE"; }
+           mv -f "$_md/$_t.old.mpr" "$_md/$MPR_BASE" || _back=0 ;;
+    *) mv -f "$_md/$_t.mpr" "$OC_COPY/$MPR_BASE" 2>/dev/null; rm -f "${_md:?}/${_t:?}.old.mpr" ;;
+  esac
+  case "$_step" in
+    *in*) mv "$_md/mprcontents" "$OC_COPY/mprcontents" || _back=0 ;;
+    *) [ -d "$_md/$_t.mprcontents" ] && mv "$_md/$_t.mprcontents" "$OC_COPY/mprcontents" ;;
+  esac
   case "$_step" in *aside*) mv "$_md/$_t.old.mprcontents" "$_md/mprcontents" || _back=0 ;; esac
-  rm -rf "$_md/$_t.mprcontents" "$_md/$_t.mpr"
-  printf '%s\n' "$OC_SIDE" | while IFS= read -r _r; do [ -n "$_r" ] && rm -f "$_md/$_r.$_t" "$_md/$_r.$_t.old"; done
   if [ "$_back" = 1 ] && [ "$(oc_fingerprint "$_md")" = "$OC_FP0" ]; then
+    rm -f "${_md:?}/${_t:?}.manifest"
     OC_WHY="the swap failed part-way (after: ${_step# }); renamed back — the live model is byte-identical to before"
   else
     restore_snapshot
+    rm -rf "${_md:?}/${_t:?}".*
     OC_WHY="the swap failed part-way and could not be renamed back; $([ "$RESTORED" = 1 ] && echo 'restored from the pre-exec snapshot' || echo 'the RESTORE FAILED too — see above')"
   fi
   return 2
 }
 
 if [ "$ON_COPY" = 1 ]; then
-  # A promotion killed between its renames leaves .mxtk-promote.* beside the model: refuse, name the fix.
-  _left="$(ls -d "$MODEL_DIR"/.mxtk-promote.* 2>/dev/null | head -3 | tr '\n' ' ')"
-  if [ -n "$_left" ]; then
-    echo "✗ --on-copy: an earlier promotion was interrupted — left behind: $_left"
-    echo "  → ./bin/restore-mpr.sh (newest snapshot = the model before that exec), then remove those paths, then re-run."
-    log_build "🚫 blocked" "on-copy: interrupted promotion left .mxtk-promote.* beside the model"
-    exit 1
-  fi
-  if ! type mxtk_copy_model_tree >/dev/null 2>&1; then
-    echo "✗ --on-copy: bin/_common.sh predates mxtk_copy_model_tree — run the toolkit's bin/sync-project.sh. Nothing was written."
+  if ! type mxtk_copy_model_tree >/dev/null 2>&1 || ! type mxtk_promote_leftovers >/dev/null 2>&1; then
+    echo "✗ --on-copy: bin/_common.sh predates mxtk_copy_model_tree / mxtk_promote_leftovers. Update it: <toolkit>/bin/sync-project.sh <project-root>"
+    echo "  (a locally edited _common.sh is held back by sync: --upgrade-bin _common.sh). Nothing was written."
     exit 1
   fi
   OC_FP0="$(oc_fingerprint "$MODEL_DIR")"   # taken BEFORE the snapshot and the copy
+  OC_SIDE0="$(oc_side_manifest "$MODEL_DIR")"
 fi
 
 echo "→ Snapshotting model..."
@@ -1150,8 +1225,14 @@ if [ "$ON_COPY" = 1 ]; then
   OC_SCR="$OC_ROOT/$(date +%Y%m%d-%H%M%S)-$$"; OC_COPY="$OC_SCR/model"; OC_MPR="$OC_COPY/$MPR_BASE"
   mkdir -p "$OC_COPY"
   _c0=$(oc_ms)
-  if ! mxtk_copy_model_tree "$MODEL_DIR" "$OC_COPY" || [ ! -f "$OC_MPR" ]; then
-    rm -rf "$OC_SCR"
+  # Single-tree checkout (the model dir is the repo root): copy the allow-list only — the .mpr and
+  # the app directories (_common.sh MXTK_APP_DIRS), never sources/, analysis/, docs/ or binaries.
+  # A two-tree app/ is all app, and is copied whole.
+  _oc_rc=0
+  if [ "$MODEL_DIR" = "$(cd "$PROJECT_ROOT" && pwd)" ]; then mxtk_copy_model_tree "$MODEL_DIR" "$OC_COPY" "$MPR_BASE" || _oc_rc=$?
+  else mxtk_copy_model_tree "$MODEL_DIR" "$OC_COPY" || _oc_rc=$?; fi
+  if [ "$_oc_rc" -ne 0 ] || [ ! -f "$OC_MPR" ]; then
+    rm -rf "${OC_SCR:?}"
     echo "✗ --on-copy: copying the model to $OC_SCR failed — nothing was written."
     log_build "🚫 blocked" "on-copy: copying the model failed — nothing written"
     exit 1
@@ -1485,14 +1566,26 @@ else
   fi
   "${PMXCLI:-./mxcli}" exec "$SCRIPT" -p "$TARGET_MPR" || EXEC_STATUS=$?
   if [ "$ON_COPY" = 1 ]; then
-    # Files exec wrote OUTSIDE the model (javasource/ for a Java action): promoted with the model.
-    # Listed now, before mxbuild writes its own output into the copy.
-    OC_SIDE="$(cd "$OC_COPY" && find . \( -path ./mprcontents -o -path ./deployment -o -path ./.mxcli \
+    # Files exec wrote OUTSIDE the model, listed now, before mxbuild writes its own output into the
+    # copy. Under $OC_SIDE_DIRS (javasource/ for a Java action) they are promoted with the model;
+    # anywhere else they refuse the promotion. The .mpr's own -wal/-shm/-journal/.lock never count.
+    _oc_all="$(cd "$OC_COPY" && find . \( -path ./mprcontents -o -path ./deployment -o -path ./.mxcli \
                  -o -path ./.git -o -path ./node_modules \) -prune -o -type f -newer "$OC_SCR/.exec-start" -print \
                2>/dev/null | sed 's|^\./||' | while IFS= read -r _r; do
-                 case "$_r" in "$MPR_BASE"|"$MPR_BASE".*) ;; *) printf '%s\n' "$_r" ;; esac
+                 case "$_r" in "$MPR_BASE"|"$MPR_BASE".*|"$MPR_BASE"-*) ;; *) printf '%s\n' "$_r" ;; esac
                done)"
-    [ -n "$OC_SIDE" ] && echo "  on-copy: mxcli exec also wrote $(printf '%s\n' "$OC_SIDE" | grep -c .) file(s) outside the model; they are promoted with it: $(printf '%s' "$OC_SIDE" | head -3 | tr '\n' ' ')"
+    OC_SIDE=""; OC_SIDE_OTHER=""
+    while IFS= read -r _r; do
+      [ -n "$_r" ] || continue
+      _in=0; for _d in $OC_SIDE_DIRS; do case "$_r" in "$_d"/*) _in=1 ;; esac; done
+      if [ "$_in" = 1 ]; then OC_SIDE="$OC_SIDE${OC_SIDE:+
+}$_r"; else OC_SIDE_OTHER="$OC_SIDE_OTHER${OC_SIDE_OTHER:+
+}$_r"; fi
+    done <<OCALL
+$_oc_all
+OCALL
+    [ -n "$OC_SIDE" ] && echo "  on-copy: mxcli exec also wrote $(printf '%s\n' "$OC_SIDE" | grep -c .) file(s) beside the model; they are promoted with it: $(printf '%s' "$OC_SIDE" | head -3 | tr '\n' ' ')"
+    [ -n "$OC_SIDE_OTHER" ] && echo "  on-copy: mxcli exec wrote outside the model and outside $OC_SIDE_DIRS: $(printf '%s' "$OC_SIDE_OTHER" | head -3 | tr '\n' ' ')— this blocks the promotion"
   fi
 fi
 
@@ -1729,7 +1822,7 @@ if [ "$ON_COPY" = 1 ]; then
     if [ "$_oc_rc" -eq 0 ]; then
       OC_NOTE="on-copy: promoted (copy ${OC_COPY_MS} ms, swap ${OC_SWAP_MS} ms)"
       echo "  ✓ promoted by rename in ${OC_SWAP_MS} ms (copy took ${OC_COPY_MS} ms); scratch copy removed."
-      rm -rf "$OC_SCR"
+      rm -rf "${OC_SCR:?}"
       if [ -n "$OC_PENDING_APPLIED" ]; then log_applied "$OC_PENDING_APPLIED"
       elif [ -n "$OC_PENDING_STATUS" ]; then log_build "$OC_PENDING_STATUS" "$OC_PENDING_DETAIL"; fi
     elif [ "$_oc_rc" -eq 1 ]; then
diff --git a/project-bin/test-scratch.sh b/project-bin/test-scratch.sh
index d9573fb6..f282388e 100755
--- a/project-bin/test-scratch.sh
+++ b/project-bin/test-scratch.sh
@@ -236,6 +236,14 @@ cleanup() {
 }
 trap cleanup EXIT
 
+# _common.sh carries the copy routine (mxtk_copy_model_tree, shared with exec.sh --on-copy). A
+# hand-edited, older _common.sh that sync-project.sh held back does not have it.
+if ! type mxtk_copy_model_tree >/dev/null 2>&1; then
+  echo "✗ test-scratch: bin/_common.sh predates mxtk_copy_model_tree. Update it: <toolkit>/bin/sync-project.sh <project-root>" >&2
+  echo "  (a locally edited _common.sh is held back by sync: --upgrade-bin _common.sh). Nothing was copied or run." >&2
+  exit 3
+fi
+
 # 1+3. Port lock first (machine-wide, cheap to fail), then the project lock for the copy.
 take_lock "$PORT_LOCK" "test ports $PORTS" || exit 3
 for _p in $PORTS; do
@@ -247,7 +255,13 @@ done
 mkdir -p "$(dirname "$EXEC_LOCK")"
 take_lock "$EXEC_LOCK" "this project's model (an exec.sh is writing it)" || exit 3
 
-# 2. The copy.
+# 2. The copy. Refused over an interrupted exec.sh --on-copy promotion (its leftovers beside the
+#    model; between its two renames there is no mprcontents/ to copy) — #384 review.
+if type mxtk_promote_leftovers >/dev/null 2>&1 && _left="$(mxtk_promote_leftovers "$MODEL_DIR" "$MPR_NAME")"; then
+  printf '%s\n' "$_left" >&2
+  echo "  Nothing was copied or run." >&2
+  exit 3
+fi
 SCRATCH="$(mktemp -d "${MXTK_SCRATCH_DIR:-${TMPDIR:-/tmp}}/$(basename "$MPR_NAME" .mpr)-test.XXXXXX")" || exit 3
 echo "→ test-scratch: copying $(basename "$MODEL_DIR")/ → $SCRATCH (no .git, .mpr-snapshots, deployment, .mxcli)"
 if ! mxtk_copy_model_tree "$MODEL_DIR" "$SCRATCH"; then
diff --git a/skills/iterative-build-loop.md b/skills/iterative-build-loop.md
index b16bee12..dd6393df 100644
--- a/skills/iterative-build-loop.md
+++ b/skills/iterative-build-loop.md
@@ -293,7 +293,7 @@ is the part worth stating twice.
 | `last-mxbuild-errors.json` is cleared at the **start** of a run, not on success | An interrupted run must not leave a previous failure's file looking like its own report |
 | Studio Pro is never auto-killed; the reopen is offered, then done on a yes | See the SP Lifecycle Rule above |
 
-**Opt-in: `./bin/exec.sh --on-copy <script>` (or `EXEC_ON_COPY=1`).** By default the live model holds the script's unverified write for the length of the gate, and keeps it if exec.sh is killed. With `--on-copy`, `mxcli exec` and the mxbuild gate run on a scratch copy under the same lock. The live model is written only by a rename-based promotion after a verified pass with exit 0. Promotion is refused while Studio Pro holds the model (even under `FORCE_EXEC`) and when the live model changed since the copy was taken. On any refusal or failure the live model is byte-identical and the copy is kept under `.mpr-snapshots/.on-copy/`, with a resume hint. It is stub-tested only and not yet the default (toolkit #350).
+**Opt-in: `./bin/exec.sh --on-copy <script>` (or `EXEC_ON_COPY=1`).** By default the live model holds the script's unverified write for the length of the gate, and keeps it if exec.sh is killed. With `--on-copy`, `mxcli exec` and the mxbuild gate run on a scratch copy under the same lock. The live model is written only by a rename-based promotion after a verified pass with exit 0. Promotion is refused while Studio Pro holds the model (even under `FORCE_EXEC`) and when the live model changed since the copy was taken. On any refusal or failure the live model is byte-identical and the copy is kept under `.mpr-snapshots/.on-copy/`, with a resume hint. On a single-tree checkout only the `.mpr` and the app directories are copied (`MXTK_APP_DIRS` in `_common.sh`), never `sources/`, `analysis/`, `docs/` or binaries. If a promotion is killed half-way, every exec and `test-scratch.sh` refuses and prints the renames that put the live model back. It is stub-tested only and not yet the default (toolkit #350).
 
 ### Standalone SP restart — `bin/restart-sp.sh`
 
diff --git a/tests/wave2/test-exec-on-copy.sh b/tests/wave2/test-exec-on-copy.sh
index 3bf51a54..9849c556 100755
--- a/tests/wave2/test-exec-on-copy.sh
+++ b/tests/wave2/test-exec-on-copy.sh
@@ -70,7 +70,8 @@ mkproj() {  # $1 = project dir, $2 = "" (root layout) or "app"
   printf 'class Old {}\n' > "$M/javasource/m/Old.java"
   printf 'CREATE MODULE "Nope";\n' > "$P/mdlsource/test.mdl"
   printf 'print("patched")\n' > "$P/mdlsource/p.sh"
-  cp "$TOOLKIT/project-bin/_common.sh" "$TOOLKIT/project-bin/restore-mpr.sh" "$TOOLKIT/project-bin/snapshot-mpr.sh" "$P/bin/"
+  cp "$TOOLKIT/project-bin/_common.sh" "$TOOLKIT/project-bin/restore-mpr.sh" "$TOOLKIT/project-bin/snapshot-mpr.sh" \
+     "$TOOLKIT/project-bin/test-scratch.sh" "$P/bin/"
   cp "$SUBJECT" "$P/bin/exec.sh"
   # mxcli: `exec <script> -p <mpr>` writes into the model it is given. STUB_EXEC_RC=1 writes half
   # and fails; STUB_SIDE=1 also writes a Java file beside the model.
@@ -84,7 +85,9 @@ echo "changed by exec" >> "$m"
 echo "changed by exec" >> "$d/mprcontents/ab/a.mxunit"
 [ "${STUB_EXEC_RC:-0}" = 1 ] && { echo "fake mxcli exec: statement 2 failed"; exit 1; }
 mkdir -p "$d/mprcontents/cd"; echo "new unit" > "$d/mprcontents/cd/new.mxunit"
-[ "${STUB_SIDE:-0}" = 1 ] && echo "class New {}" > "$d/javasource/m/New.java"
+[ "${STUB_SIDE:-0}" = 1 ] && { echo "class New {}" > "$d/javasource/m/New.java"; echo "// edited" >> "$d/javasource/m/Old.java"; }
+[ "${STUB_OTHER:-0}" = 1 ] && { mkdir -p "$d/other"; echo x > "$d/other/x.txt"; }
+[ "${STUB_JOURNAL:-0}" = 1 ] && echo j > "$m-journal"
 echo "fake mxcli exec ok"; exit 0
 MXCLI
   chmod +x "$P/bin/"*.sh "$P/mxcli"
@@ -129,7 +132,7 @@ for LAYOUT in root app; do
   grep -q 'changed by exec' "$M/mprcontents/ab/a.mxunit" && ok "live unit holds the change" || bad "live unit unchanged"
   [ -f "$M/mprcontents/cd/new.mxunit" ] && ok "new unit promoted" || bad "new unit missing"
   [ -f "$M/javasource/m/New.java" ] && ok "file exec wrote outside the model promoted" || bad "javasource/m/New.java not promoted"
-  [ -f "$M/javasource/m/Old.java" ] && ok "untouched file outside the model still there" || bad "Old.java lost"
+  grep -q '// edited' "$M/javasource/m/Old.java" && ok "edited file beside the model promoted" || bad "Old.java edit not promoted"
   [ -z "$(ls -d "$M"/.mxtk-promote.* 2>/dev/null)" ] && ok "no promotion leftovers" || bad "leftovers: $(ls -d "$M"/.mxtk-promote.*)"
   [ -z "$(ls -A "$P/.mpr-snapshots/.on-copy" 2>/dev/null)" ] && ok "scratch copy removed after promotion" || bad "scratch copy left: $(ls "$P/.mpr-snapshots/.on-copy")"
   [ "$(rows "$P")" = 1 ] && ok "exactly one BUILD-LOG row" || bad "BUILD-LOG rows: $(rows "$P")"
@@ -193,8 +196,91 @@ for LAYOUT in root app; do
   [ "$(fp "$M")" = "$B" ] && ok "live model byte-identical after the failed swap" || bad "live model differs after a failed swap"
   [ -z "$(ls -d "$M"/.mxtk-promote.* 2>/dev/null)" ] && ok "no leftovers" || bad "leftovers: $(ls -d "$M"/.mxtk-promote.*)"
   has "row says promotion failed" "$(cat "$P/docs/BUILD-LOG.md")" "promotion failed"
+  K="$(ls -d "$P/.mpr-snapshots/.on-copy/"*/ 2>/dev/null | head -1)"
+  [ -n "$K" ] && grep -q 'changed by exec' "$K/model/Fixture.mpr" && [ -f "$K/model/mprcontents/cd/new.mxunit" ] \
+    && ok "L1: the kept copy is whole after the rollback" || bad "L1: kept copy incomplete after rollback"
+  hasnt "L1: no 'incomplete' note when the copy is whole" "$OUT" "is incomplete"
+
+  echo "-- M1/M2: killed between the two mprcontents renames"
+  P="$WORK/$LAYOUT-killed"; mkproj "$P" "$SUB"; M="$P${SUB:+/$SUB}"
+  B="$(fp "$M")"
+  _MXTK_TEST_SWAP_KILL=mprcontents run "$P" --on-copy mdlsource/test.mdl >/dev/null
+  [ ! -d "$M/mprcontents" ] && ok "[setup] the kill left the live model with no mprcontents/" || bad "[setup] kill did not land between the renames"
+  OUT="$(run "$P" mdlsource/test.mdl)"; RC=$?
+  [ "$RC" -eq 1 ] && ok "M1: the DEFAULT exec refuses (rc 1)" || bad "M1: default exec rc $RC"
+  [ ! -f "$WORK/log/exec-targets" ] && ok "M1: nothing executed" || bad "M1: exec ran over a half-swapped model"
+  has "M2: says half-swapped" "$OUT" "interrupted part-way"
+  has "M2: prints the rename back" "$OUT" "mv '$M/.mxtk-promote."
+  has "M2: restore-mpr only as last resort" "$OUT" "Last resort only"
+  has "M2: says what restore-mpr drops" "$OUT" "DROPS every model change"
+  OUT2="$(cd "$P" && STUB_LOG="$WORK/log" bash ./bin/test-scratch.sh -- x 2>&1)"; RC=$?
+  [ "$RC" -eq 3 ] && ok "M1: test-scratch refuses the copy (rc 3)" || bad "M1: test-scratch rc $RC: $(printf '%s' "$OUT2" | tail -3)"
+  has "M1: test-scratch names the interrupted promotion" "$OUT2" "interrupted part-way"
+  printf '%s\n' "$OUT" | sed -n 's/^ *\(mv .*\|rm .*\)$/\1/p' > "$WORK/fix.sh"
+  bash "$WORK/fix.sh" 2>"$WORK/fix.err"
+  [ ! -s "$WORK/fix.err" ] && ok "M2: every printed command ran without an error" || bad "M2: printed commands erred: $(cat "$WORK/fix.err")"
+  [ "$(fp "$M")" = "$B" ] && ok "M2: the printed commands put the live model back byte-identical" || bad "M2: live differs after the printed commands"
+  OUT="$(run "$P" mdlsource/test.mdl)"; RC=$?
+  [ "$RC" -eq 0 ] && ok "M1: default exec runs again after the fix" || bad "M1: rc $RC after fix: $(printf '%s' "$OUT" | tail -3)"
+
+  echo "-- M2: killed after a side file was promoted"
+  P="$WORK/$LAYOUT-killside"; mkproj "$P" "$SUB"; M="$P${SUB:+/$SUB}"
+  B="$(fp "$M")"
+  STUB_SIDE=1 _MXTK_TEST_SWAP_KILL=side run "$P" --on-copy mdlsource/test.mdl >/dev/null
+  OUT="$(run "$P" --on-copy mdlsource/test.mdl)"; RC=$?
+  [ "$RC" -eq 1 ] && ok "refused (rc 1)" || bad "rc $RC"
+  has "M2: names the side-file original to rename back" "$OUT" ".mxtk-promote."
+  printf '%s\n' "$OUT" | sed -n 's/^ *\(mv .*\|rm .*\)$/\1/p' > "$WORK/fix.sh"
+  bash "$WORK/fix.sh" 2>"$WORK/fix.err"
+  [ ! -s "$WORK/fix.err" ] && ok "M2: every printed command ran without an error" || bad "M2: printed commands erred: $(cat "$WORK/fix.err")"
+  [ "$(fp "$M")" = "$B" ] && ok "M2: model AND side files back byte-identical" || bad "M2: live differs after the side-file commands"
+  [ ! -f "$M/javasource/m/New.java" ] && ok "M2: the file the promotion created is removed" || bad "M2: New.java left behind"
+
+  echo "-- M2: only staged leftovers — live intact, delete them"
+  P="$WORK/$LAYOUT-staged"; mkproj "$P" "$SUB"; M="$P${SUB:+/$SUB}"
+  mkdir "$M/.mxtk-promote.999.mprcontents"; printf 'x\n' > "$M/.mxtk-promote.999.mpr"
+  OUT="$(run "$P" mdlsource/test.mdl)"; RC=$?
+  [ "$RC" -eq 1 ] && ok "refused (rc 1)" || bad "rc $RC"
+  has "M2: says the live model is intact" "$OUT" "the live model is intact"
+  hasnt "M2: no rename-back for staged-only" "$OUT" "mv '"
+
+  echo "-- M3: a side file changed live during the exec"
+  P="$WORK/$LAYOUT-sidechg"; mkproj "$P" "$SUB"; M="$P${SUB:+/$SUB}"
+  OUT="$(STUB_SIDE=1 STUB_MXB_TOUCH="$M/javasource/m/Old.java" run "$P" --on-copy mdlsource/test.mdl)"; RC=$?
+  [ "$RC" -eq 1 ] && ok "M3: refused (rc 1)" || bad "M3: rc $RC: $(printf '%s' "$OUT" | tail -3)"
+  has "M3: names the file" "$OUT" "changed live since the copy was taken: javasource/m/Old.java"
+  grep -q 'changed by exec' "$M/Fixture.mpr" && bad "M3: model promoted anyway" || ok "M3: model not promoted"
+  grep -q 'edited by someone else' "$M/javasource/m/Old.java" && ok "M3: the live edit survives" || bad "M3: live edit lost"
+
+  echo "-- a write outside the model and the side dirs refuses; -journal is never a side file"
+  P="$WORK/$LAYOUT-other"; mkproj "$P" "$SUB"; M="$P${SUB:+/$SUB}"
+  OUT="$(STUB_OTHER=1 STUB_JOURNAL=1 run "$P" --on-copy mdlsource/test.mdl)"; RC=$?
+  [ "$RC" -eq 1 ] && ok "refused (rc 1)" || bad "rc $RC"
+  has "names the stray write" "$OUT" "other/x.txt"
+  hasnt "-journal not listed as a write" "$OUT" "Fixture.mpr-journal"
+  P="$WORK/$LAYOUT-journal"; mkproj "$P" "$SUB"; M="$P${SUB:+/$SUB}"
+  OUT="$(STUB_JOURNAL=1 run "$P" --on-copy mdlsource/test.mdl)"; RC=$?
+  [ "$RC" -eq 0 ] && [ ! -f "$M/Fixture.mpr-journal" ] && ok "L2: -journal never promoted" || bad "L2: rc $RC, journal promoted?"
+
+  echo "-- nit: FORCE_EXEC with Studio Pro open refuses --on-copy up front"
+  P="$WORK/$LAYOUT-force"; mkproj "$P" "$SUB"; M="$P${SUB:+/$SUB}"
+  sleep 60 & SPP=$!; BG="$BG $SPP"; printf '{"ProcessId":%s}\n' "$SPP" > "$M/Fixture.mpr.lock"
+  OUT="$(FORCE_EXEC=1 run "$P" --on-copy mdlsource/test.mdl)"; RC=$?
+  [ "$RC" -eq 1 ] && ok "refused (rc 1)" || bad "rc $RC"
+  has "says FORCE_EXEC does not override" "$OUT" "FORCE_EXEC does not override"
+  [ ! -f "$WORK/log/exec-targets" ] && ok "nothing executed" || bad "exec ran"
+  kill "$SPP" 2>/dev/null
 done
 
+echo "== L4: single-tree copy is the allow-list"
+P="$WORK/allow"; mkproj "$P" ""
+mkdir -p "$P/analysis" "$P/sources"; echo big > "$P/analysis/a.txt"; echo src > "$P/sources/s.txt"
+STUB_MXB_ERR=1 run "$P" --on-copy mdlsource/test.mdl >/dev/null
+K="$(ls -d "$P/.mpr-snapshots/.on-copy/"*/ 2>/dev/null | head -1)"
+[ -n "$K" ] && [ -f "$K/model/Fixture.mpr" ] && [ -d "$K/model/mprcontents" ] && [ -d "$K/model/javasource" ] && ok "model + app dirs copied" || bad "copy lacks the model"
+[ -n "$K" ] && [ ! -e "$K/model/analysis" ] && [ ! -e "$K/model/sources" ] && [ ! -e "$K/model/mxcli" ] && [ ! -e "$K/model/mdlsource" ] \
+  && ok "analysis/, sources/, mdlsource/ and the mxcli binary not copied" || bad "copy holds non-app paths: $(ls "$K/model")"
+
 echo "== env and options"
 echo "-- EXEC_ON_COPY=1 is the same as --on-copy"
 P="$WORK/env"; mkproj "$P" ""

From 1aef3d3059d01ffbcb7563983c25089e8024bdfb Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 14 Oct 2026 16:37:43 +0000
Subject: [PATCH 3/7] =?UTF-8?q?fix(exec):=20#384=20HOLD=20=E2=80=94=20idem?=
 =?UTF-8?q?potent=20--recover-promote=20replaces=20printed=20commands?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The printed recovery commands could destroy the live model (run twice, or an
rm after a failed mv). Replaced by one entry point, `exec.sh --recover-promote`
(mxtk_promote_recover in _common.sh), under the exec lock:
- oc_promote writes .mxtk-promote.N.committed after every rename is done and
  verified; with it, recovery only finishes the cleanup (old files).
- without it, recovery rolls back by rename from the manifest (which now also
  records whether live and copy had mprcontents/), each step guarded by what
  is on disk, so a second run is a no-op; new files go back to the kept copy
  or to a trash dir removed only after every rename succeeded. A hard-linked
  .old (mpr or side file) still -ef the live file means "never replaced".
- leftovers without a manifest are refused untouched (exit 2).
- the same function is the in-process rollback and the staging undo
  (oc_unstage removed). The refusal message names the command only.
Side files are now found by checksum against the pre-copy manifest, not mtime
(an archive-dated file was missed). mlsource added to MXTK_APP_DIRS.

Fixture: a kill in each of 8 windows (manifest, staged, between the
mprcontents renames, after the .mpr, between a side file's link and its
rename, after a side file, committed, mid-cleanup), recovery run twice, the
live model is the pre-exec or the promoted model, never a mix. 241 checks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 CHANGELOG.md                     |   2 +-
 project-bin/_common.sh           | 147 +++++++++++++--------
 project-bin/exec.sh              | 217 ++++++++++++++-----------------
 project-bin/test-scratch.sh      |   6 +-
 skills/iterative-build-loop.md   |   2 +-
 tests/wave2/test-exec-on-copy.sh | 102 ++++++++-------
 6 files changed, 247 insertions(+), 229 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 33675d29..0faba19e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,7 +19,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are. Named m
 
 ## Unreleased
 
-- new(exec): **`exec.sh --on-copy` (or `EXEC_ON_COPY=1`), opt-in: the script and the mxbuild gate run on a scratch copy, and the live model is written only by a rename-based promotion after a verified pass** ([#350](https://github.com/MendixMau/mxcli-project-toolkit/issues/350)). By default the live model holds an unverified write for the length of the gate (22-65 s per apply in the field), and keeps it when exec.sh is killed. Promotion is refused while Studio Pro holds the model (even under `FORCE_EXEC`), when the live model changed since the copy (cksum manifest), or when the copy is on another filesystem. A swap that fails part-way renames back, else restores the snapshot. On any other outcome the live model is untouched and the copy is kept under `.mpr-snapshots/.on-copy/` with a resume hint (newest 3 kept). Files exec writes beside the model (javasource/, javascriptsource/, theme/...) are promoted with it only if their live copy still matches its pre-copy checksum; a write anywhere else refuses. A single-tree checkout copies only the `.mpr` and the app directories, never sources/, analysis/, docs/ or binaries. A promotion killed half-way leaves `.mxtk-promote.*` names: every exec.sh path (the default one included) and `test-scratch.sh` then refuse and print the exact renames that put the live model back, with `restore-mpr.sh` only as the last resort. The default path is otherwise unchanged. The copy routine moved from `test-scratch.sh` into `_common.sh` (`mxtk_copy_model_tree`, `mxtk_promote_leftovers`). Fixture `tests/wave2/test-exec-on-copy.sh` (176 checks, both layouts). Bench `tests/wave2/bench-exec-on-copy.sh` (stub mxbuild 2 s, an input): with exec.sh killed mid-gate the live model stayed byte-identical in 0/10 default runs and 10/10 on-copy runs at 500, 5,000 and 20,000 units. The broken window fell from about 2.1 s (clean) and 5.5-25.4 s (failed gate) to a 15-42 ms swap, at a cost of +1.4 s, +3.7 s and +10.9 s wall time per exec. Field evidence: none yet (stub-only); a field run with Studio Pro closed and then open is owed before it can become the default. Statement-level resume from the kept copy is a follow-up. — external review (#350), MendixMau
+- new(exec): **`exec.sh --on-copy` (or `EXEC_ON_COPY=1`), opt-in: the script and the mxbuild gate run on a scratch copy, and the live model is written only by a rename-based promotion after a verified pass** ([#350](https://github.com/MendixMau/mxcli-project-toolkit/issues/350)). By default the live model holds an unverified write for the length of the gate (22-65 s per apply in the field), and keeps it when exec.sh is killed. Promotion is refused while Studio Pro holds the model (even under `FORCE_EXEC`), when the live model changed since the copy (cksum manifest), or when the copy is on another filesystem. A swap that fails part-way renames back, else restores the snapshot. On any other outcome the live model is untouched and the copy is kept under `.mpr-snapshots/.on-copy/` with a resume hint (newest 3 kept). Files exec writes beside the model (javasource/, javascriptsource/, theme/...; found by checksum) are promoted with it only if their live copy still matches its pre-copy checksum; a write anywhere else refuses. A single-tree checkout copies only the `.mpr` and the app directories, never sources/, analysis/, docs/ or binaries. A promotion killed half-way leaves `.mxtk-promote.*` names: every exec.sh path (the default one included) and `test-scratch.sh` then refuse until `./bin/exec.sh --recover-promote` finishes a committed promotion or renames the live model back (idempotent; a commit marker decides which; `restore-mpr.sh` only as the last resort). The default path is otherwise unchanged. The copy routine moved from `test-scratch.sh` into `_common.sh` (`mxtk_copy_model_tree`, `mxtk_promote_leftovers`). Fixture `tests/wave2/test-exec-on-copy.sh` (241 checks, both layouts; a kill in each of 8 promotion windows, recovered twice, is the pre-exec or the promoted model, never a mix). Bench `tests/wave2/bench-exec-on-copy.sh` (stub mxbuild 2 s, an input): with exec.sh killed mid-gate the live model stayed byte-identical in 0/10 default runs and 10/10 on-copy runs at 500, 5,000 and 20,000 units. The broken window fell from about 2.1 s (clean) and 5.5-25.4 s (failed gate) to a 15-42 ms swap, at a cost of +1.4 s, +3.7 s and +10.9 s wall time per exec. Field evidence: none yet (stub-only); a field run with Studio Pro closed and then open is owed before it can become the default. Statement-level resume from the kept copy is a follow-up. — external review (#350), MendixMau
 - process(build): **Stage 5 drafts the ready set in parallel and applies serially.** The runbook dispatch row said "sequential within a module", which serialised drafting even for independent scripts; it now points to `iterative-build-loop.md` → Gate cost, the single statement of the rule. The unit is the build-plan row: every `BUILD` row whose "Depends on" rows are all applied, minus overlapping writers (two rows that replace, alter or drop+create the same document never share a ready set, and no row is drafted while it overlaps a queued unapplied one; `brd-to-build-plan.md` has Produces name every document a row writes), runs at once, its scripts in order, one `mdl-agent` per script. Applies stay one at a time through `bin/exec.sh`, and the ready set is recomputed after each. A queued draft made before a sibling apply landed is re-checked with `mxcli diff --format struct` (preflight STOP rule 23); any removal line (checked against `describe` per BUG-146) or STOP rule 21 target means re-draft, never patch, because a stale restatement of a shared document is exactly rule 21's silent seed-call loss and passes `check --references`. Report `ready set N, drafted N, applied k`; the `mdl-agent` template says a drafter never applies and never depends on an unapplied draft. Field evidence: none yet. — MendixMau
 - fix(platform-link): **CLI commits now show their changed documents in Studio Pro History.** Studio Pro's History → Model changes pane reads a `ModelChanges` array from the commit's `refs/notes/mx_metadata` note. Trap 6c's hand-written template set it to `[]`, so every mxcli/agent commit showed "Model changes 0" (field project: 270 of 270 notes empty). New `project-bin/mx-metadata-note.py` (stdlib only) computes the array from the commit's changed `.mxunit` files, in Studio Pro's entry shape: Status, UnitID, UnitType, UnitName and Module (walked up the `.mpr` Unit tree). It has `changes` / `write` / `backfill` / `sync <remote>` subcommands. `install-project-hooks.sh` now also installs post-commit and post-rewrite hooks that write the note and never block, and `--check` covers them, so `sync-project.sh` rolls them out to wired projects. Notes are published with `mx-metadata-note.py sync <remote>` after the branch push. Push config is never touched. With mxcli v0.26+ in the project root the hooks call `mxcli git note --write` instead (mendixlabs/mxcli#1337); the Python script is the fallback for older pins, and on 160 field commits both wrote the same 3,594 entries. Trap 6c rewritten. Measured against Studio Pro's own notes, 51 commits in 5 apps: 3387/3389 entries exact on all five fields. Field run on a 357-commit Mendix 11.15.0 app: 158 notes backfilled and pushed, and Studio Pro History lists the documents per revision. Review fixes: an earlier revision added `HEAD` + the notes ref to `remote.<r>.push`. It was dropped because any push refspec replaces `push.default`. A branch tracking a differently named upstream got a new same-named branch on Team Server where `simple` refuses, a missing local notes ref failed the whole push, and nobody knows whether Studio Pro's own push reads that config. The installer now only fetches the remote's notes (non-forced). It removes that exact `HEAD` + notes pair if present, and leaves and reports any other entry. `sync` handles a remote with no notes ref (it used to exit 1) and retries a rejected push once after re-merging. A note that already lists changes (Studio Pro's) is never overwritten by `write`/`backfill` without `--force`, and `sync` keeps a colleague's non-empty note over ours. The mxcli probe greps `git note --help` for `--write`. Hooks and docs call the script through `resolve_py`. Fixture `tests/wave2/test-mx-metadata-note.sh` (40 cases, over real captured template units; single- and two-tree layouts, amend, backfill and `--force`, push exit codes identical to a no-hooks clone, leftover-refspec cleanup, sync to an empty remote and its retry, notes fetch at install, a diverged notes merge; green under `init.defaultBranch` master and main). — field project (Mendix 11.15 app), MendixMau
 - learn(fixture-seeding): **explore the data structure first, choose rows by use case, scan actions for resets before any run.** Two seeding runs on public template apps: seeding raised journey passes 33 -> 58 and 20 -> 51 of the same sets (FAIL 93 -> 68, 163 -> 132; INVALID unchanged), and a "Reset all demodata" journey wiped accounts so 104 of 127 journeys reported `The username or password you entered is incorrect`, identical on empty and seeded databases. Skill gains three questions a seed must answer, a use-case checklist, a destructive-action scan, a generic traps table with symptoms, measured expectations and a denominator checklist; routing trigger now fires on seed/test/demo data and empty pages. Independent review fixes: object ids follow the Mendix bigint pattern with a business-key guard (no uuids), associations are seeded where the page's path stores them, four new traps (enum names, inheritance chain, calculated attributes, view/external entities), and the port-offset and container-label traps moved to `harness-architecture.md`. — MendixMau
diff --git a/project-bin/_common.sh b/project-bin/_common.sh
index c5f46ded..4dbfe1df 100755
--- a/project-bin/_common.sh
+++ b/project-bin/_common.sh
@@ -655,7 +655,7 @@ mxtk_mxbuild_why() {
 # Used by bin/test-scratch.sh (mxcli test, #278; two args) and bin/exec.sh --on-copy (#350). tar
 # preserves mtimes, which --on-copy relies on to tell the files `mxcli exec` wrote from the files
 # it copied. Returns tar's status.
-MXTK_APP_DIRS="${MXTK_APP_DIRS:-mprcontents widgets javasource javascriptsource theme themesource userlib vendorlib resources nativemobile}"
+MXTK_APP_DIRS="${MXTK_APP_DIRS:-mprcontents widgets javasource javascriptsource theme themesource userlib vendorlib resources nativemobile mlsource}"
 mxtk_copy_model_tree() {
   if [ -z "${3:-}" ]; then
     tar -C "$1" --exclude=./.git --exclude=./.mpr-snapshots --exclude=./deployment \
@@ -668,71 +668,110 @@ mxtk_copy_model_tree() {
   tar -C "$_src" --exclude=node_modules -cf - "$@" | tar -C "$_dst" -xf -
 }
 
-# mxtk_promote_leftovers <model-dir> <mpr-basename> — 0 (and a diagnosis on stdout) iff an
-# exec.sh --on-copy promotion was killed part-way and left its files beside the model. Every
-# model writer and copier calls this first (exec.sh on every path, test-scratch.sh): a kill
-# between the two mprcontents/ renames leaves NO mprcontents/, and a default exec would then
-# snapshot and write that (#384 review). Names, all under <model-dir>, for promotion PID N:
-#   .mxtk-promote.N.manifest        side files of that promotion, "E <rel>" (existed live) / "N <rel>"
-#   .mxtk-promote.N.mpr / .mprcontents   staged new model — never live yet
-#   .mxtk-promote.N.old.mpr / .old.mprcontents   the live model, moved aside by the swap
-#   <rel>.mxtk-promote.N            a staged side file;  <rel>.mxtk-promote.N.old  its live original
-# The printed commands put the pre-promotion live model back by rename — every rename the swap
-# did, undone — then remove the rest. Only the glob runs when there is nothing: cheap per exec.
+# ── Interrupted exec.sh --on-copy promotions (#350, #384 review) ─────────────────────────────
+# oc_promote (exec.sh) leaves these names beside the model for promotion PID N, in this order:
+#   .mxtk-promote.N.manifest   written FIRST: "L 0|1" (live had mprcontents/), "C 0|1" (the copy
+#                              had), then "E <rel>" / "N <rel>" per side file (existed live / new)
+#   .mxtk-promote.N.mpr / .mprcontents       staged new model (never live)
+#   <rel>.mxtk-promote.N                     a staged side file (never live)
+#   .mxtk-promote.N.old.mpr                  hard link of the live .mpr, taken before the swap
+#   .mxtk-promote.N.old.mprcontents          the live mprcontents/, moved aside by the swap
+#   <rel>.mxtk-promote.N.old                 hard link of a live side file, taken before its swap
+#   .mxtk-promote.N.committed                every rename done and verified; only cleanup is left
+# A kill between the two mprcontents/ renames leaves NO mprcontents/, so every model writer and
+# copier (exec.sh on every path, test-scratch.sh) refuses while any of these exist.
+
+# mxtk_promote_leftovers <model-dir> — prints the PIDs of interrupted promotions; 0 iff any.
 mxtk_promote_leftovers() {
-  local md="$1" mb="$2" f n pids="" p t cmds k rel any_old
-  for f in "$md"/.mxtk-promote.*; do
+  local f n pids=""
+  for f in "$1"/.mxtk-promote.*; do
     [ -e "$f" ] || continue
     n="${f##*/.mxtk-promote.}"; n="${n%%.*}"
     case " $pids " in *" $n "*) ;; *) pids="$pids $n" ;; esac
   done
   [ -n "$pids" ] || return 1
-  for p in $pids; do
-    t="$md/.mxtk-promote.$p"; cmds=""; any_old=0
-    if [ -d "$t.old.mprcontents" ]; then
-      any_old=1
-      [ -d "$md/mprcontents" ] && cmds="$cmds
-mv '$md/mprcontents' '$t.new.mprcontents'"
-      cmds="$cmds
-mv '$t.old.mprcontents' '$md/mprcontents'"
-    fi
-    # .old.mpr is a hard link taken before the swap; while it is still the live file (-ef), the
-    # .mpr was not replaced and the rm at the end is enough.
-    if [ -f "$t.old.mpr" ] && ! [ "$t.old.mpr" -ef "$md/$mb" ]; then
-      any_old=1; cmds="$cmds
-mv -f '$t.old.mpr' '$md/$mb'"
-    fi
-    if [ -f "$t.manifest" ]; then
-      while read -r k rel; do
-        [ -n "$rel" ] || continue
-        if [ -f "$md/$rel.mxtk-promote.$p.old" ]; then
-          any_old=1; cmds="$cmds
-mv -f '$md/$rel.mxtk-promote.$p.old' '$md/$rel'"
-        elif [ "$k" = N ] && [ ! -f "$md/$rel.mxtk-promote.$p" ] && [ -f "$md/$rel" ]; then
-          any_old=1; cmds="$cmds
-rm -f '$md/$rel'"   # created by the promotion; did not exist before it
-        fi
-        [ -f "$md/$rel.mxtk-promote.$p" ] && cmds="$cmds
-rm -f '$md/$rel.mxtk-promote.$p'"
-      done < "$t.manifest"
+  echo $pids
+}
+
+# mxtk_promote_recover <model-dir> <mpr-basename> <pid> [<handback-dir>] — finish or undo one
+# interrupted promotion. Idempotent: every step is guarded by what is on disk, so a second run (or
+# a run after a killed run) is a no-op or finishes the job. Never deletes a live file: anything it
+# takes out of the live tree goes back to <handback-dir> (the kept copy) or into .mxtk-promote.N.trash,
+# and the trash is removed only after every rename succeeded.
+#   .committed present -> the live model IS the promoted one: remove the .old leftovers only.
+#   no .committed      -> roll back to the pre-promotion live model, by rename.
+# Returns 0 done · 1 a rename failed (nothing deleted; re-run) · 2 ambiguous (nothing touched).
+mxtk_promote_recover() {
+  local md="$1" mb="$2" p="$3" hb="${4:-}" t s f k rel lv=1 cv=1 ok=1
+  t="$md/.mxtk-promote.$p"; s="mxtk-promote.$p"
+  _pr_out() {  # $1 = path in the live tree, $2 = its rel path in the copy: hand back, else trash
+    if [ -n "$hb" ] && [ ! -e "$hb/$2" ]; then mkdir -p "$(dirname "$hb/$2")" && mv "$1" "$hb/$2" && return 0; fi
+    mkdir -p "$t.trash/$(dirname "$2")" && mv "$1" "$t.trash/$2.$$"
+  }
+  if [ ! -f "$t.manifest" ]; then
+    for f in "$t".*; do
+      [ -e "$f" ] || continue
+      case "$f" in "$t.fsprobe"|"$t.trash") ;; *)
+        echo "✗ promotion $p: $f exists but its manifest does not — cannot tell what it is. Nothing touched."
+        return 2 ;; esac
+    done
+    rm -rf "${t:?}.fsprobe" "${t:?}.trash"; return 0
+  fi
+  if [ -f "$t.committed" ]; then
+    rm -rf "${t:?}.old.mprcontents" "${t:?}.old.mpr" "${t:?}.trash" || return 1
+    while read -r k rel; do
+      case "$k" in E|N) rm -f "${md:?}/${rel:?}.${s:?}.old" ;; esac
+    done < "$t.manifest"
+    rm -f "${t:?}.manifest" "${t:?}.fsprobe" && rm -f "${t:?}.committed"
+    echo "  promotion $p had committed: the live model is the promoted one; leftovers removed."
+    return 0
+  fi
+  lv="$(sed -n 's/^L //p' "$t.manifest")"; cv="$(sed -n 's/^C //p' "$t.manifest")"
+  if [ -d "$t.old.mprcontents" ] && [ -d "$md/mprcontents" ] && [ -e "$t.new.mprcontents" ]; then
+    echo "✗ promotion $p: mprcontents/, its .old and its .new all exist — cannot tell which is live. Nothing touched."
+    return 2
+  fi
+  # 1. Side files: put each original back (a hard link to the live file means it was never swapped).
+  while read -r k rel; do
+    case "$k" in E|N) ;; *) continue ;; esac
+    if [ -f "$md/$rel.$s.old" ]; then
+      if [ "$md/$rel.$s.old" -ef "$md/$rel" ]; then mkdir -p "$t.trash" && mv "$md/$rel.$s.old" "$t.trash/side.$$" || ok=0
+      else
+        [ -f "$md/$rel" ] && { _pr_out "$md/$rel" "$rel" || ok=0; }
+        mv -f "$md/$rel.$s.old" "$md/$rel" || ok=0
+      fi
+    elif [ "$k" = N ] && [ ! -f "$md/$rel.$s" ] && [ -f "$md/$rel" ]; then
+      _pr_out "$md/$rel" "$rel" || ok=0   # added by the promotion; did not exist before it
     fi
-    cmds="$cmds
-rm -rf '$t'.*"
-    if [ "$any_old" = 1 ]; then
-      echo "✗ An exec.sh --on-copy promotion (PID $p) was interrupted part-way: the live model may be half-swapped."
-      echo "  Put the live model back as it was before that promotion, by rename (run these in order):"
+    [ -f "$md/$rel.$s" ] && { _pr_out "$md/$rel.$s" "$rel" || ok=0; }
+  done < "$t.manifest"
+  # 2. The .mpr.
+  if [ -f "$t.old.mpr" ]; then
+    if [ "$t.old.mpr" -ef "$md/$mb" ]; then mkdir -p "$t.trash" && mv "$t.old.mpr" "$t.trash/mpr.$$" || ok=0
     else
-      echo "✗ An exec.sh --on-copy promotion (PID $p) was interrupted before it replaced anything: the live model is intact."
-      echo "  Only staged files are left. Remove them:"
+      if [ -n "$hb" ] && [ ! -e "$hb/$mb" ]; then ln "$md/$mb" "$hb/$mb" 2>/dev/null || cp -p "$md/$mb" "$hb/$mb"; fi
+      mv -f "$t.old.mpr" "$md/$mb" || ok=0
     fi
-    printf '%s\n' "$cmds" | grep . | sed 's/^/      /'
-  done
-  echo "  Then re-run. Last resort only: ./bin/restore-mpr.sh restores the newest snapshot (the model before"
-  echo "  that exec) and DROPS every model change made after that snapshot was taken."
+  fi
+  [ -f "$t.mpr" ] && { _pr_out "$t.mpr" "$mb" || ok=0; }
+  # 3. mprcontents/.
+  if [ -d "$t.old.mprcontents" ]; then
+    if [ -d "$md/mprcontents" ]; then mv "$md/mprcontents" "$t.new.mprcontents" || ok=0; fi
+    [ "$ok" = 1 ] && { mv "$t.old.mprcontents" "$md/mprcontents" || ok=0; }
+  elif [ "$lv" = 0 ] && [ "$cv" = 1 ] && [ ! -d "$t.mprcontents" ] && [ -d "$md/mprcontents" ]; then
+    mv "$md/mprcontents" "$t.new.mprcontents" || ok=0   # a v1 live model: the promotion added it
+  fi
+  [ -d "$t.new.mprcontents" ] && { _pr_out "$t.new.mprcontents" mprcontents || ok=0; }
+  [ -d "$t.mprcontents" ] && { _pr_out "$t.mprcontents" mprcontents || ok=0; }
+  if [ "$ok" != 1 ] || { [ "$lv" = 1 ] && [ ! -d "$md/mprcontents" ]; }; then
+    echo "✗ promotion $p: a rename failed — nothing was deleted. Fix the cause and run it again."
+    return 1
+  fi
+  rm -rf "${t:?}.trash" && rm -f "${t:?}.fsprobe" "${t:?}.manifest"
+  echo "  promotion $p had not committed: rolled back by rename; the live model is the one before it."
   return 0
 }
 
-
 # project_name — the .mpr basename without extension, for user-facing messages.
 project_name() {
   local mpr
diff --git a/project-bin/exec.sh b/project-bin/exec.sh
index 67386f56..da6d6dd9 100755
--- a/project-bin/exec.sh
+++ b/project-bin/exec.sh
@@ -19,6 +19,7 @@
 #        ./bin/exec.sh --cr CR-07 <script.mdl>        (any mode: tag the run with its change request)
 #        ./bin/exec.sh --on-copy <script.mdl>         (opt-in, or EXEC_ON_COPY=1: write a scratch
 #                                                     copy, promote it only on a clean gate)
+#        ./bin/exec.sh --recover-promote              (finish or undo an interrupted --on-copy promotion)
 #        Leading flags (--cr, --commit-first, --on-copy, then --patch) may come in any order.
 #
 # --on-copy (opt-in, 2026-10-14, #350): `mxcli exec` and the mxbuild gate run on a scratch COPY
@@ -32,12 +33,13 @@
 # renames only: .mpr is replaced by one rename (atomic); mprcontents/ by two (live -> aside, new ->
 # live), so for the microseconds between them there is no mprcontents/ (rename(2) cannot exchange
 # two directories portably). Files `mxcli exec` wrote beside the model under OC_SIDE_DIRS
-# (javasource/ for a Java action) are promoted the same way, one rename each, and only if the live
+# (javasource/ for a Java action; found by checksum, not mtime) are promoted the same way, one rename each, and only if the live
 # file still matches its pre-copy checksum; a write anywhere else refuses the promotion, and a file
 # exec DELETED is not mirrored (follow-up). A swap that fails half-way renames back (the copy is
 # handed back whole), else restores the pre-exec snapshot. A promotion KILLED half-way leaves
-# .mxtk-promote.* names that every exec.sh path and test-scratch.sh refuse on, printing the exact
-# renames that put the live model back (mxtk_promote_leftovers, _common.sh). On a single-tree
+# .mxtk-promote.* names that every exec.sh path and test-scratch.sh refuse on, until
+# `./bin/exec.sh --recover-promote` finishes it (committed) or renames it back (mxtk_promote_recover,
+# _common.sh: idempotent, by rename, never deletes a live file). On a single-tree
 # checkout only the .mpr and the app directories (MXTK_APP_DIRS) are copied, never sources/,
 # analysis/, docs/ or binaries. On any other outcome the live model is never written and the copy is
 # kept with a resume hint; the newest MXTK_ON_COPY_KEEP (default 3) survive. Not with --patch.
@@ -194,7 +196,7 @@ mxtk_change_class() {  # $1 = MDL script; prints "<class>\t<why>"
 # `[--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=""
-ON_COPY="${EXEC_ON_COPY:-0}"; [ "$ON_COPY" = 1 ] || ON_COPY=0; ON_COPY_FLAG=0
+ON_COPY="${EXEC_ON_COPY:-0}"; [ "$ON_COPY" = 1 ] || ON_COPY=0; ON_COPY_FLAG=0; RECOVER=0
 while [ $# -gt 0 ]; do
   case "$1" in
     --cr)
@@ -210,6 +212,7 @@ while [ $# -gt 0 ]; do
       shift 2 ;;
     --commit-first) COMMIT_FIRST=1; shift ;;
     --on-copy) ON_COPY=1; ON_COPY_FLAG=1; shift ;;
+    --recover-promote) RECOVER=1; shift ;;
     --patch) PATCH_MODE=1; shift; break ;;
     --change-class|--watch-compat) ADVISORY="$1"; shift; break ;;
     *) break ;;
@@ -354,6 +357,7 @@ MPR_BASE="$(basename "$MPR")"
 NAME="$(basename "$MPR" .mpr)"
 SCRIPT="${1:-}"
 [ $# -gt 0 ] && shift
+[ "$RECOVER" = 1 ] && { SCRIPT="recover-promote"; ON_COPY=0; }
 # Remaining args go to the patch script, after the model path. An MDL run takes none.
 LOG_NAME="$(basename "$SCRIPT")"
 [ "$PATCH_MODE" = "1" ] && LOG_NAME="patch: $LOG_NAME"
@@ -662,15 +666,27 @@ if command -v pgrep >/dev/null 2>&1; then
 fi
 
 # 3b. An exec.sh --on-copy promotion killed part-way (#350, #384 review) leaves .mxtk-promote.*
-#    beside the model, and between its two renames NO mprcontents/. Every path refuses until it is
-#    put back, so a default exec never snapshots and writes a half-swapped model. The diagnosis and
-#    the exact rename commands come from mxtk_promote_leftovers (_common.sh); the check is one glob.
-if type mxtk_promote_leftovers >/dev/null 2>&1 && _oc_left="$(mxtk_promote_leftovers "$MODEL_DIR" "$MPR_BASE")"; then
-  printf '%s\n' "$_oc_left"
-  echo "  Nothing was snapshotted or executed."
-  log_build "🚫 blocked" "interrupted --on-copy promotion left .mxtk-promote.* beside the model"
-  exit 1
+#    beside the model, and between its two renames NO mprcontents/. Every path refuses until
+#    `./bin/exec.sh --recover-promote` has finished or undone it (mxtk_promote_recover, _common.sh:
+#    idempotent, by rename, under this lock). The check is one glob.
+if type mxtk_promote_leftovers >/dev/null 2>&1 && _oc_pids="$(mxtk_promote_leftovers "$MODEL_DIR")"; then
+  if [ "$RECOVER" != 1 ]; then
+    echo "✗ An exec.sh --on-copy promotion (PID $_oc_pids) was interrupted: .mxtk-promote.* is beside the model,"
+    echo "  which may be half-swapped. Nothing was snapshotted or executed."
+    echo "  → ./bin/exec.sh --recover-promote   (finishes a committed promotion, else renames the live model back;"
+    echo "    safe to run twice). Last resort only: ./bin/restore-mpr.sh, which drops every change after its snapshot."
+    log_build "🚫 blocked" "interrupted --on-copy promotion (PID $_oc_pids) — run exec.sh --recover-promote"
+    exit 1
+  fi
+  _oc_rc=0
+  for _p in $_oc_pids; do
+    _hb="$(ls -d "$PROJECT_ROOT/.mpr-snapshots/.on-copy/"*-"$_p"/model 2>/dev/null | head -1)"
+    mxtk_promote_recover "$MODEL_DIR" "$MPR_BASE" "$_p" "$_hb" || _oc_rc=$?
+  done
+  log_build "$([ "$_oc_rc" = 0 ] && echo '↩ promotion recovered' || echo '✗ recovery incomplete')" "exec.sh --recover-promote, PID $_oc_pids (exit $_oc_rc)"
+  exit "$_oc_rc"
 fi
+if [ "$RECOVER" = 1 ]; then echo "  Nothing to recover: no interrupted --on-copy promotion beside the model."; exit 0; fi
 
 # 4. Uncommitted model changes. The snapshot taken below would not cover them,
 #    so a failed gate would auto-restore to a state pre-dating those changes and
@@ -1042,6 +1058,14 @@ oc_side_sum() {  # $1 = file: "crc size", or "-" when it does not exist
 oc_side_sum0() {  # $1 = rel path: its "crc size" in OC_SIDE0 (taken before the copy), or "-"
   printf '%s\n' "$OC_SIDE0" | awk -v r="$1" '{ c = $1; s = $2; p = $0; sub(/^[^ ]+ [^ ]+ /, "", p); if (p == r) { print c, s; f = 1; exit } } END { if (!f) print "-" }'
 }
+oc_other_list() {  # $1 = copy [$2 = marker: only files newer]: sorted paths outside the model and $OC_SIDE_DIRS
+  ( cd "$1" && find . \( -path ./mprcontents -o -path ./deployment -o -path ./.mxcli -o -path ./.git \
+      -o -path ./node_modules \) -prune -o -type f ${2:+-newer "$2"} -print 2>/dev/null | sed 's|^\./||' | while IFS= read -r _r; do
+      case "$_r" in "$MPR_BASE"|"$MPR_BASE".*|"$MPR_BASE"-*) continue ;; esac
+      _in=0; for _d in $OC_SIDE_DIRS; do case "$_r" in "$_d"/*) _in=1 ;; esac; done
+      [ "$_in" = 1 ] || printf '%s\n' "$_r"
+    done | LC_ALL=C sort )
+}
 oc_prune() {  # keep the newest $OC_KEEP kept copies
   ls -dt "$OC_ROOT"/*/ 2>/dev/null | tail -n +$((OC_KEEP + 1)) | while read -r _d; do rm -rf "${_d:?}"; done
 }
@@ -1050,7 +1074,7 @@ oc_keep_hint() {
     echo "  The copy is kept: $OC_COPY"
     echo "    It holds what the script did. Look at it: ./mxcli -p $OC_MPR -c \"SHOW STRUCTURE\""
   else
-    echo "  The copy at $OC_COPY is incomplete (the failed swap could not hand all of it back); it is kept for inspection only."
+    echo "  The copy at $OC_COPY is incomplete (the failed swap could not hand it all back); kept for inspection only."
   fi
   echo "  Resume: fix the script and re-run ./bin/exec.sh --on-copy $SCRIPT — it starts from a fresh copy"
   echo "    of the live model. Resuming THIS copy with only the statements that did not land is not built"
@@ -1058,21 +1082,14 @@ oc_keep_hint() {
   oc_prune
   echo "  The newest $OC_KEEP kept copies stay under .mpr-snapshots/.on-copy/ (MXTK_ON_COPY_KEEP); older ones were removed."
 }
-oc_unstage() {  # put staged files back into the copy (nothing in the live model was replaced yet)
-  [ -f "$MODEL_DIR/$_t.mpr" ] && mv "$MODEL_DIR/$_t.mpr" "$OC_COPY/$MPR_BASE" 2>/dev/null
-  [ -d "$MODEL_DIR/$_t.mprcontents" ] && mv "$MODEL_DIR/$_t.mprcontents" "$OC_COPY/mprcontents" 2>/dev/null
-  printf '%s\n' "$OC_SIDE" | while IFS= read -r _r; do
-    [ -n "$_r" ] && [ -f "$MODEL_DIR/$_r.$_st" ] && mv "$MODEL_DIR/$_r.$_st" "$OC_COPY/$_r" 2>/dev/null
-  done
-  rm -f "${MODEL_DIR:?}/${_t:?}.manifest" "${MODEL_DIR:?}/${_t:?}.old.mpr"
-  return 0
-}
+oc_hook() { [ "${_MXTK_TEST_SWAP_KILL:-}" = "$1" ] && kill -KILL $$; return 0; }   # fixture: kill at window $1
 # oc_promote — 0 promoted · 1 refused, the live model untouched · 2 the swap failed part-way
 # (rolled back by rename, else restored from the pre-exec snapshot; OC_WHY says which).
-# Every name it leaves beside the model is one mxtk_promote_leftovers (_common.sh) can read back,
-# so a promotion killed at any point is recoverable by rename on the next run.
+# Every name it leaves beside the model is listed in _common.sh above mxtk_promote_leftovers, and
+# the one undo — here on a failure, and from `exec.sh --recover-promote` after a kill — is
+# mxtk_promote_recover: idempotent, by rename, handing new files back to the copy.
 oc_promote() {
-  _md="$MODEL_DIR"; _t=".mxtk-promote.$$"; _st="mxtk-promote.$$"; _step=""
+  _md="$MODEL_DIR"; _t="$MODEL_DIR/.mxtk-promote.$$"; _st="mxtk-promote.$$"
   OC_WHY=""
   if sp_holds_model; then
     OC_WHY="Studio Pro holds $NAME (lock PID $SP_PID); its in-memory model would overwrite the promotion on its next save"; return 1
@@ -1088,11 +1105,11 @@ oc_promote() {
   fi
   # A rename across filesystems is a copy. ln (a hard link) fails across filesystems, on every platform.
   : > "$OC_SCR/.fsprobe"
-  if ! ln "$OC_SCR/.fsprobe" "$_md/$_t.fsprobe" 2>/dev/null; then
+  if ! ln "$OC_SCR/.fsprobe" "$_t.fsprobe" 2>/dev/null; then
     rm -f "${OC_SCR:?}/.fsprobe"
     OC_WHY="the copy is not on the model's filesystem, so the swap could not be a rename"; return 1
   fi
-  rm -f "${OC_SCR:?}/.fsprobe" "${_md:?}/${_t:?}.fsprobe"
+  rm -f "${OC_SCR:?}/.fsprobe" "${_t:?}.fsprobe"
   # Side files exec will promote that exist live must still be what was copied (#384 M3).
   _changed=""
   while IFS= read -r _r; do
@@ -1104,61 +1121,51 @@ OCSIDE
   if [ -n "$_changed" ]; then
     OC_WHY="a file the promotion would replace changed live since the copy was taken:$_changed"; return 1
   fi
-  # The manifest first, so a kill from here on leaves something mxtk_promote_leftovers can read.
-  printf '%s\n' "$OC_SIDE" | while IFS= read -r _r; do
-    [ -n "$_r" ] || continue
-    if [ -f "$_md/$_r" ]; then echo "E $_r"; else echo "N $_r"; fi
-  done > "$_md/$_t.manifest"
+  # The manifest FIRST: from here on a kill leaves something mxtk_promote_recover can read.
+  { echo "L $([ -d "$_md/mprcontents" ] && echo 1 || echo 0)"; echo "C $([ -d "$OC_COPY/mprcontents" ] && echo 1 || echo 0)"
+    printf '%s\n' "$OC_SIDE" | while IFS= read -r _r; do
+      [ -n "$_r" ] || continue
+      if [ -f "$_md/$_r" ]; then echo "E $_r"; else echo "N $_r"; fi
+    done; } > "$_t.manifest"
+  oc_hook manifest
   # Stage beside the live files (renames). Nothing live is replaced yet.
   OC_UNITS=0
   [ -d "$OC_COPY/mprcontents" ] && OC_UNITS=$(find "$OC_COPY/mprcontents" -type f | wc -l | tr -d ' ')
-  if ! mv "$OC_COPY/$MPR_BASE" "$_md/$_t.mpr" \
-     || { [ -d "$OC_COPY/mprcontents" ] && ! mv "$OC_COPY/mprcontents" "$_md/$_t.mprcontents"; }; then
-    oc_unstage; OC_WHY="staging the copy beside the live model failed"; return 1
-  fi
-  _sidefail=0
-  while IFS= read -r _r; do
+  _ok=1
+  mv "$OC_COPY/$MPR_BASE" "$_t.mpr" || _ok=0
+  [ "$_ok" = 1 ] && [ -d "$OC_COPY/mprcontents" ] && { mv "$OC_COPY/mprcontents" "$_t.mprcontents" || _ok=0; }
+  while [ "$_ok" = 1 ] && IFS= read -r _r; do
     [ -n "$_r" ] || continue
-    mkdir -p "$_md/$(dirname "$_r")" && mv "$OC_COPY/$_r" "$_md/$_r.$_st" || { _sidefail=1; break; }
+    mkdir -p "$_md/$(dirname "$_r")" && mv "$OC_COPY/$_r" "$_md/$_r.$_st" || _ok=0
   done <<OCSIDE
 $OC_SIDE
 OCSIDE
-  if [ "$_sidefail" = 1 ]; then oc_unstage; OC_WHY="staging a file mxcli exec wrote outside the model failed"; return 1; fi
+  oc_hook staged
   # Last checks, right before the swap: the live model is what was copied, and SP is still closed.
-  if [ "$(oc_fingerprint "$_md")" != "$OC_FP0" ]; then
-    oc_unstage
-    OC_WHY="the live model changed since the copy was taken (Studio Pro save, git checkout, another writer); promoting would drop that change"; return 1
-  fi
-  if sp_holds_model; then
-    oc_unstage; OC_WHY="Studio Pro opened $NAME (lock PID $SP_PID) during the exec"; return 1
+  if [ "$_ok" != 1 ]; then OC_WHY="staging the copy beside the live model failed"
+  elif [ "$(oc_fingerprint "$_md")" != "$OC_FP0" ]; then
+    OC_WHY="the live model changed since the copy was taken (Studio Pro save, git checkout, another writer); promoting would drop that change"
+  elif sp_holds_model; then OC_WHY="Studio Pro opened $NAME (lock PID $SP_PID) during the exec"
   fi
-  # The swap: renames only. Old files stay beside the new ones until the swap is verified.
+  if [ -n "$OC_WHY" ]; then mxtk_promote_recover "$_md" "$MPR_BASE" $$ "$OC_COPY" >/dev/null; return 1; fi
+  # The swap: renames only. Old files stay beside the new ones (hard links) until it is verified.
   _s0=$(oc_ms); OC_LIVE_WRITTEN=1
-  { ln "$_md/$MPR_BASE" "$_md/$_t.old.mpr" 2>/dev/null || cp -p "$_md/$MPR_BASE" "$_md/$_t.old.mpr"; } || { oc_unstage; OC_LIVE_WRITTEN=0; OC_WHY="could not keep the old .mpr aside"; return 1; }
-  _ok=1
-  if [ -d "$_md/mprcontents" ]; then
-    if mv "$_md/mprcontents" "$_md/$_t.old.mprcontents"; then _step="aside"; else _ok=0; fi
-  fi
-  if [ "${_MXTK_TEST_SWAP_KILL:-}" = mprcontents ]; then kill -KILL $$; fi   # fixture hook: killed between the two renames
-  if [ "$_ok" = 1 ] && [ -d "$_md/$_t.mprcontents" ]; then
-    if mv "$_md/$_t.mprcontents" "$_md/mprcontents"; then _step="$_step in"; else _ok=0; fi
-  fi
+  { ln "$_md/$MPR_BASE" "$_t.old.mpr" 2>/dev/null || cp -p "$_md/$MPR_BASE" "$_t.old.mpr"; } || _ok=0
+  [ "$_ok" = 1 ] && [ -d "$_md/mprcontents" ] && { mv "$_md/mprcontents" "$_t.old.mprcontents" || _ok=0; }
+  oc_hook mprcontents
+  [ "$_ok" = 1 ] && [ -d "$_t.mprcontents" ] && { mv "$_t.mprcontents" "$_md/mprcontents" || _ok=0; }
   [ "${_MXTK_TEST_SWAP_FAIL:-}" = mpr ] && _ok=0   # fixture hook: fail before the .mpr rename
-  if [ "$_ok" = 1 ]; then
-    if mv -f "$_md/$_t.mpr" "$_md/$MPR_BASE"; then _step="$_step mpr"; else _ok=0; fi
-  fi
-  _sides=""
-  if [ "$_ok" = 1 ]; then
-    while IFS= read -r _r; do
-      [ -n "$_r" ] || continue
-      [ -f "$_md/$_r" ] && { ln "$_md/$_r" "$_md/$_r.$_st.old" 2>/dev/null || cp -p "$_md/$_r" "$_md/$_r.$_st.old"; }
-      if mv -f "$_md/$_r.$_st" "$_md/$_r"; then _sides="$_sides
-$_r"; else _ok=0; break; fi
-      if [ "${_MXTK_TEST_SWAP_KILL:-}" = side ]; then kill -KILL $$; fi   # fixture hook: killed after a side file
-    done <<OCSIDE
+  [ "$_ok" = 1 ] && { mv -f "$_t.mpr" "$_md/$MPR_BASE" || _ok=0; }
+  oc_hook mpr
+  while [ "$_ok" = 1 ] && IFS= read -r _r; do
+    [ -n "$_r" ] || continue
+    [ -f "$_md/$_r" ] && { ln "$_md/$_r" "$_md/$_r.$_st.old" 2>/dev/null || cp -p "$_md/$_r" "$_md/$_r.$_st.old"; }
+    [ -f "$_md/$_r.$_st.old" ] && oc_hook side-ln   # window: linked, not yet replaced
+    mv -f "$_md/$_r.$_st" "$_md/$_r" || _ok=0
+    oc_hook side
+  done <<OCSIDE
 $OC_SIDE
 OCSIDE
-  fi
   _s1=$(oc_ms)   # the renames are done: this is the end of the window the live model is mixed
   if [ "$_ok" = 1 ] && [ "$OC_UNITS" -gt 0 ] \
      && [ "$(find "$_md/mprcontents" -type f 2>/dev/null | wc -l | tr -d ' ')" -ne "$OC_UNITS" ]; then
@@ -1166,50 +1173,25 @@ OCSIDE
   fi
   if [ "$_ok" = 1 ]; then
     OC_SWAP_MS=$(( _s1 - _s0 ))
-    # Old files out of the model dir, into the scratch dir, then the scratch dir goes.
-    [ -d "$_md/$_t.old.mprcontents" ] && mv "$_md/$_t.old.mprcontents" "$OC_SCR/old-mprcontents"
-    rm -f "${_md:?}/${_t:?}.old.mpr"
-    printf '%s\n' "$OC_SIDE" | while IFS= read -r _r; do [ -n "$_r" ] && rm -f "${_md:?}/${_r:?}.${_st:?}.old"; done
-    rm -f "${_md:?}/${_t:?}.manifest"
+    : > "$_t.committed"   # from here on, recovery FINISHES the promotion instead of undoing it
+    oc_hook committed
+    if [ "${_MXTK_TEST_SWAP_KILL:-}" = cleanup ]; then rm -rf "${_t:?}.old.mprcontents"; kill -KILL $$; fi
+    mxtk_promote_recover "$_md" "$MPR_BASE" $$ >/dev/null
     return 0
   fi
-  # Part-way failure: undo by rename, newest step first, handing every new file back to the copy
-  # so the kept copy stays whole (#384 L1); anything that fails -> the snapshot.
-  _back=1
-  printf '%s\n' "$_sides" | while IFS= read -r _r; do
-    [ -n "$_r" ] || continue
-    mkdir -p "$OC_COPY/$(dirname "$_r")"; mv -f "$_md/$_r" "$OC_COPY/$_r"
-    [ -f "$_md/$_r.$_st.old" ] && mv -f "$_md/$_r.$_st.old" "$_md/$_r"
-  done
-  printf '%s\n' "$OC_SIDE" | while IFS= read -r _r; do
-    [ -n "$_r" ] || continue
-    [ -f "$_md/$_r.$_st" ] && mv -f "$_md/$_r.$_st" "$OC_COPY/$_r"
-    rm -f "${_md:?}/${_r:?}.${_st:?}.old"
-  done
-  case "$_step" in
-    *mpr*) { ln "$_md/$MPR_BASE" "$OC_COPY/$MPR_BASE" 2>/dev/null || cp -p "$_md/$MPR_BASE" "$OC_COPY/$MPR_BASE"; }
-           mv -f "$_md/$_t.old.mpr" "$_md/$MPR_BASE" || _back=0 ;;
-    *) mv -f "$_md/$_t.mpr" "$OC_COPY/$MPR_BASE" 2>/dev/null; rm -f "${_md:?}/${_t:?}.old.mpr" ;;
-  esac
-  case "$_step" in
-    *in*) mv "$_md/mprcontents" "$OC_COPY/mprcontents" || _back=0 ;;
-    *) [ -d "$_md/$_t.mprcontents" ] && mv "$_md/$_t.mprcontents" "$OC_COPY/mprcontents" ;;
-  esac
-  case "$_step" in *aside*) mv "$_md/$_t.old.mprcontents" "$_md/mprcontents" || _back=0 ;; esac
-  if [ "$_back" = 1 ] && [ "$(oc_fingerprint "$_md")" = "$OC_FP0" ]; then
-    rm -f "${_md:?}/${_t:?}.manifest"
-    OC_WHY="the swap failed part-way (after: ${_step# }); renamed back — the live model is byte-identical to before"
+  if mxtk_promote_recover "$_md" "$MPR_BASE" $$ "$OC_COPY" >/dev/null && [ "$(oc_fingerprint "$_md")" = "$OC_FP0" ]; then
+    OC_WHY="the swap failed part-way; renamed back — the live model is byte-identical to before"
   else
     restore_snapshot
-    rm -rf "${_md:?}/${_t:?}".*
-    OC_WHY="the swap failed part-way and could not be renamed back; $([ "$RESTORED" = 1 ] && echo 'restored from the pre-exec snapshot' || echo 'the RESTORE FAILED too — see above')"
+    OC_WHY="the swap failed part-way and could not be renamed back; $([ "$RESTORED" = 1 ] && echo 'restored from the pre-exec snapshot (run ./bin/exec.sh --recover-promote to clear the leftovers)' || echo 'the RESTORE FAILED too — see above')"
   fi
   return 2
 }
 
+
 if [ "$ON_COPY" = 1 ]; then
-  if ! type mxtk_copy_model_tree >/dev/null 2>&1 || ! type mxtk_promote_leftovers >/dev/null 2>&1; then
-    echo "✗ --on-copy: bin/_common.sh predates mxtk_copy_model_tree / mxtk_promote_leftovers. Update it: <toolkit>/bin/sync-project.sh <project-root>"
+  if ! type mxtk_copy_model_tree >/dev/null 2>&1 || ! type mxtk_promote_recover >/dev/null 2>&1; then
+    echo "✗ --on-copy: bin/_common.sh predates mxtk_copy_model_tree / mxtk_promote_recover. Update it: <toolkit>/bin/sync-project.sh <project-root>"
     echo "  (a locally edited _common.sh is held back by sync: --upgrade-bin _common.sh). Nothing was written."
     exit 1
   fi
@@ -1563,27 +1545,20 @@ else
   if [ "$ON_COPY" = 1 ]; then
     OC_PHASE="gate"; OC_NOTE="on-copy: live model not written, copy kept at $OC_SCR"
     : > "$OC_SCR/.exec-start"   # tar kept the copied files' mtimes: anything newer, exec wrote
+    oc_other_list "$OC_COPY" > "$OC_SCR/.pre"
   fi
   "${PMXCLI:-./mxcli}" exec "$SCRIPT" -p "$TARGET_MPR" || EXEC_STATUS=$?
   if [ "$ON_COPY" = 1 ]; then
     # Files exec wrote OUTSIDE the model, listed now, before mxbuild writes its own output into the
-    # copy. Under $OC_SIDE_DIRS (javasource/ for a Java action) they are promoted with the model;
-    # anywhere else they refuse the promotion. The .mpr's own -wal/-shm/-journal/.lock never count.
-    _oc_all="$(cd "$OC_COPY" && find . \( -path ./mprcontents -o -path ./deployment -o -path ./.mxcli \
-                 -o -path ./.git -o -path ./node_modules \) -prune -o -type f -newer "$OC_SCR/.exec-start" -print \
-               2>/dev/null | sed 's|^\./||' | while IFS= read -r _r; do
-                 case "$_r" in "$MPR_BASE"|"$MPR_BASE".*|"$MPR_BASE"-*) ;; *) printf '%s\n' "$_r" ;; esac
-               done)"
-    OC_SIDE=""; OC_SIDE_OTHER=""
-    while IFS= read -r _r; do
-      [ -n "$_r" ] || continue
-      _in=0; for _d in $OC_SIDE_DIRS; do case "$_r" in "$_d"/*) _in=1 ;; esac; done
-      if [ "$_in" = 1 ]; then OC_SIDE="$OC_SIDE${OC_SIDE:+
-}$_r"; else OC_SIDE_OTHER="$OC_SIDE_OTHER${OC_SIDE_OTHER:+
-}$_r"; fi
-    done <<OCALL
-$_oc_all
-OCALL
+    # copy. Under $OC_SIDE_DIRS (javasource/ for a Java action): every file whose checksum differs
+    # from OC_SIDE0 or that is new — by content, never mtime, so an archive-dated file counts — is
+    # promoted with the model. Anywhere else, a new path or an mtime past the marker refuses the
+    # promotion. The .mpr's own -wal/-shm/-journal/.lock never count.
+    oc_side_manifest "$OC_COPY" | LC_ALL=C sort > "$OC_SCR/.side1"
+    printf '%s\n' "$OC_SIDE0" | grep . | LC_ALL=C sort > "$OC_SCR/.side0"
+    OC_SIDE="$(LC_ALL=C comm -13 "$OC_SCR/.side0" "$OC_SCR/.side1" | sed 's/^[^ ]* [^ ]* //')"
+    oc_other_list "$OC_COPY" > "$OC_SCR/.post"
+    OC_SIDE_OTHER="$( { LC_ALL=C comm -13 "$OC_SCR/.pre" "$OC_SCR/.post"; oc_other_list "$OC_COPY" "$OC_SCR/.exec-start"; } | LC_ALL=C sort -u)"
     [ -n "$OC_SIDE" ] && echo "  on-copy: mxcli exec also wrote $(printf '%s\n' "$OC_SIDE" | grep -c .) file(s) beside the model; they are promoted with it: $(printf '%s' "$OC_SIDE" | head -3 | tr '\n' ' ')"
     [ -n "$OC_SIDE_OTHER" ] && echo "  on-copy: mxcli exec wrote outside the model and outside $OC_SIDE_DIRS: $(printf '%s' "$OC_SIDE_OTHER" | head -3 | tr '\n' ' ')— this blocks the promotion"
   fi
diff --git a/project-bin/test-scratch.sh b/project-bin/test-scratch.sh
index f282388e..934a23bd 100755
--- a/project-bin/test-scratch.sh
+++ b/project-bin/test-scratch.sh
@@ -257,9 +257,9 @@ take_lock "$EXEC_LOCK" "this project's model (an exec.sh is writing it)" || exit
 
 # 2. The copy. Refused over an interrupted exec.sh --on-copy promotion (its leftovers beside the
 #    model; between its two renames there is no mprcontents/ to copy) — #384 review.
-if type mxtk_promote_leftovers >/dev/null 2>&1 && _left="$(mxtk_promote_leftovers "$MODEL_DIR" "$MPR_NAME")"; then
-  printf '%s\n' "$_left" >&2
-  echo "  Nothing was copied or run." >&2
+if type mxtk_promote_leftovers >/dev/null 2>&1 && _left="$(mxtk_promote_leftovers "$MODEL_DIR")"; then
+  echo "✗ test-scratch: an exec.sh --on-copy promotion (PID $_left) was interrupted; the model may be half-swapped." >&2
+  echo "  → ./bin/exec.sh --recover-promote, then re-run. Nothing was copied or run." >&2
   exit 3
 fi
 SCRATCH="$(mktemp -d "${MXTK_SCRATCH_DIR:-${TMPDIR:-/tmp}}/$(basename "$MPR_NAME" .mpr)-test.XXXXXX")" || exit 3
diff --git a/skills/iterative-build-loop.md b/skills/iterative-build-loop.md
index dd6393df..9dc02f3c 100644
--- a/skills/iterative-build-loop.md
+++ b/skills/iterative-build-loop.md
@@ -293,7 +293,7 @@ is the part worth stating twice.
 | `last-mxbuild-errors.json` is cleared at the **start** of a run, not on success | An interrupted run must not leave a previous failure's file looking like its own report |
 | Studio Pro is never auto-killed; the reopen is offered, then done on a yes | See the SP Lifecycle Rule above |
 
-**Opt-in: `./bin/exec.sh --on-copy <script>` (or `EXEC_ON_COPY=1`).** By default the live model holds the script's unverified write for the length of the gate, and keeps it if exec.sh is killed. With `--on-copy`, `mxcli exec` and the mxbuild gate run on a scratch copy under the same lock. The live model is written only by a rename-based promotion after a verified pass with exit 0. Promotion is refused while Studio Pro holds the model (even under `FORCE_EXEC`) and when the live model changed since the copy was taken. On any refusal or failure the live model is byte-identical and the copy is kept under `.mpr-snapshots/.on-copy/`, with a resume hint. On a single-tree checkout only the `.mpr` and the app directories are copied (`MXTK_APP_DIRS` in `_common.sh`), never `sources/`, `analysis/`, `docs/` or binaries. If a promotion is killed half-way, every exec and `test-scratch.sh` refuses and prints the renames that put the live model back. It is stub-tested only and not yet the default (toolkit #350).
+**Opt-in: `./bin/exec.sh --on-copy <script>` (or `EXEC_ON_COPY=1`).** By default the live model holds the script's unverified write for the length of the gate, and keeps it if exec.sh is killed. With `--on-copy`, `mxcli exec` and the mxbuild gate run on a scratch copy under the same lock. The live model is written only by a rename-based promotion after a verified pass with exit 0. Promotion is refused while Studio Pro holds the model (even under `FORCE_EXEC`) and when the live model changed since the copy was taken. On any refusal or failure the live model is byte-identical and the copy is kept under `.mpr-snapshots/.on-copy/`, with a resume hint. On a single-tree checkout only the `.mpr` and the app directories are copied (`MXTK_APP_DIRS` in `_common.sh`), never `sources/`, `analysis/`, `docs/` or binaries. If a promotion is killed half-way, every exec and `test-scratch.sh` refuses until `./bin/exec.sh --recover-promote` has finished it or renamed it back; it is safe to run twice. It is stub-tested only and not yet the default (toolkit #350).
 
 ### Standalone SP restart — `bin/restart-sp.sh`
 
diff --git a/tests/wave2/test-exec-on-copy.sh b/tests/wave2/test-exec-on-copy.sh
index 9849c556..64a4783b 100755
--- a/tests/wave2/test-exec-on-copy.sh
+++ b/tests/wave2/test-exec-on-copy.sh
@@ -21,7 +21,10 @@
 #   a swap that fails half-way (fixture hook) is renamed back: live byte-identical;
 #   EXEC_ON_COPY=1 is the same as --on-copy; flag unset runs on the live model as before;
 #   kept copies are pruned to MXTK_ON_COPY_KEEP; --on-copy --patch is refused; EXEC_ON_COPY=1
-#   with --patch runs the patch as before; leftovers of an interrupted promotion refuse.
+#   with --patch runs the patch as before;
+#   a kill in each of 8 promotion windows: the default exec and test-scratch refuse, and
+#   `exec.sh --recover-promote` run TWICE leaves the pre-exec or the promoted model, never a mix;
+#   leftovers without a manifest are refused untouched; a side file with an archive mtime is promoted.
 # Stub mxcli and mxbuild record the model path they were given. No real model, mxcli or mxbuild.
 set -uo pipefail
 
@@ -88,6 +91,7 @@ mkdir -p "$d/mprcontents/cd"; echo "new unit" > "$d/mprcontents/cd/new.mxunit"
 [ "${STUB_SIDE:-0}" = 1 ] && { echo "class New {}" > "$d/javasource/m/New.java"; echo "// edited" >> "$d/javasource/m/Old.java"; }
 [ "${STUB_OTHER:-0}" = 1 ] && { mkdir -p "$d/other"; echo x > "$d/other/x.txt"; }
 [ "${STUB_JOURNAL:-0}" = 1 ] && echo j > "$m-journal"
+[ "${STUB_OLDMTIME:-0}" = 1 ] && { echo "class Arch {}" > "$d/javasource/m/Arch.java"; touch -t 200001010000 "$d/javasource/m/Arch.java"; }
 echo "fake mxcli exec ok"; exit 0
 MXCLI
   chmod +x "$P/bin/"*.sh "$P/mxcli"
@@ -201,48 +205,56 @@ for LAYOUT in root app; do
     && ok "L1: the kept copy is whole after the rollback" || bad "L1: kept copy incomplete after rollback"
   hasnt "L1: no 'incomplete' note when the copy is whole" "$OUT" "is incomplete"
 
-  echo "-- M1/M2: killed between the two mprcontents renames"
-  P="$WORK/$LAYOUT-killed"; mkproj "$P" "$SUB"; M="$P${SUB:+/$SUB}"
-  B="$(fp "$M")"
-  _MXTK_TEST_SWAP_KILL=mprcontents run "$P" --on-copy mdlsource/test.mdl >/dev/null
-  [ ! -d "$M/mprcontents" ] && ok "[setup] the kill left the live model with no mprcontents/" || bad "[setup] kill did not land between the renames"
-  OUT="$(run "$P" mdlsource/test.mdl)"; RC=$?
-  [ "$RC" -eq 1 ] && ok "M1: the DEFAULT exec refuses (rc 1)" || bad "M1: default exec rc $RC"
-  [ ! -f "$WORK/log/exec-targets" ] && ok "M1: nothing executed" || bad "M1: exec ran over a half-swapped model"
-  has "M2: says half-swapped" "$OUT" "interrupted part-way"
-  has "M2: prints the rename back" "$OUT" "mv '$M/.mxtk-promote."
-  has "M2: restore-mpr only as last resort" "$OUT" "Last resort only"
-  has "M2: says what restore-mpr drops" "$OUT" "DROPS every model change"
-  OUT2="$(cd "$P" && STUB_LOG="$WORK/log" bash ./bin/test-scratch.sh -- x 2>&1)"; RC=$?
-  [ "$RC" -eq 3 ] && ok "M1: test-scratch refuses the copy (rc 3)" || bad "M1: test-scratch rc $RC: $(printf '%s' "$OUT2" | tail -3)"
-  has "M1: test-scratch names the interrupted promotion" "$OUT2" "interrupted part-way"
-  printf '%s\n' "$OUT" | sed -n 's/^ *\(mv .*\|rm .*\)$/\1/p' > "$WORK/fix.sh"
-  bash "$WORK/fix.sh" 2>"$WORK/fix.err"
-  [ ! -s "$WORK/fix.err" ] && ok "M2: every printed command ran without an error" || bad "M2: printed commands erred: $(cat "$WORK/fix.err")"
-  [ "$(fp "$M")" = "$B" ] && ok "M2: the printed commands put the live model back byte-identical" || bad "M2: live differs after the printed commands"
-  OUT="$(run "$P" mdlsource/test.mdl)"; RC=$?
-  [ "$RC" -eq 0 ] && ok "M1: default exec runs again after the fix" || bad "M1: rc $RC after fix: $(printf '%s' "$OUT" | tail -3)"
-
-  echo "-- M2: killed after a side file was promoted"
-  P="$WORK/$LAYOUT-killside"; mkproj "$P" "$SUB"; M="$P${SUB:+/$SUB}"
-  B="$(fp "$M")"
-  STUB_SIDE=1 _MXTK_TEST_SWAP_KILL=side run "$P" --on-copy mdlsource/test.mdl >/dev/null
-  OUT="$(run "$P" --on-copy mdlsource/test.mdl)"; RC=$?
-  [ "$RC" -eq 1 ] && ok "refused (rc 1)" || bad "rc $RC"
-  has "M2: names the side-file original to rename back" "$OUT" ".mxtk-promote."
-  printf '%s\n' "$OUT" | sed -n 's/^ *\(mv .*\|rm .*\)$/\1/p' > "$WORK/fix.sh"
-  bash "$WORK/fix.sh" 2>"$WORK/fix.err"
-  [ ! -s "$WORK/fix.err" ] && ok "M2: every printed command ran without an error" || bad "M2: printed commands erred: $(cat "$WORK/fix.err")"
-  [ "$(fp "$M")" = "$B" ] && ok "M2: model AND side files back byte-identical" || bad "M2: live differs after the side-file commands"
-  [ ! -f "$M/javasource/m/New.java" ] && ok "M2: the file the promotion created is removed" || bad "M2: New.java left behind"
+  echo "-- kill windows: recovery run TWICE is the pre-exec model (not committed) or the promoted one (committed), never a mix"
+  T="$WORK/$LAYOUT-twin"; mkproj "$T" "$SUB"
+  STUB_SIDE=1 run "$T" --on-copy mdlsource/test.mdl >/dev/null
+  PROMOTED="$(fp "$T${SUB:+/$SUB}")"
+  B0="$(mkproj "$WORK/$LAYOUT-pristine" "$SUB"; fp "$WORK/$LAYOUT-pristine${SUB:+/$SUB}")"
+  [ -n "$PROMOTED" ] && [ "$PROMOTED" != "$B0" ] && ok "[setup] promoted and pre-exec models differ" || bad "[setup] promoted == pre-exec: the window checks prove nothing"
+  for W in manifest staged mprcontents mpr side-ln side committed cleanup; do
+    P="$WORK/$LAYOUT-kill-$W"; mkproj "$P" "$SUB"; M="$P${SUB:+/$SUB}"
+    B="$(fp "$M")"
+    STUB_SIDE=1 _MXTK_TEST_SWAP_KILL="$W" run "$P" --on-copy mdlsource/test.mdl >/dev/null 2>&1
+    [ -n "$(ls -d "$M"/.mxtk-promote.* 2>/dev/null)" ] && ok "[$W] the kill left leftovers" || bad "[$W] [setup] no leftovers — the kill missed its window"
+    if [ "$W" = mprcontents ]; then
+      [ ! -d "$M/mprcontents" ] && ok "[$W] [setup] live model has no mprcontents/" || bad "[$W] [setup] mprcontents/ present"
+      OUT="$(run "$P" mdlsource/test.mdl)"; RC=$?
+      [ "$RC" -eq 1 ] && ok "[$W] M1: the DEFAULT exec refuses" || bad "[$W] M1: default exec rc $RC"
+      [ ! -f "$WORK/log/exec-targets" ] && ok "[$W] M1: nothing executed" || bad "[$W] M1: exec ran over a half-swapped model"
+      has "[$W] M2: the refusal names the recovery command" "$OUT" "./bin/exec.sh --recover-promote"
+      hasnt "[$W] M2: no shell commands printed" "$OUT" "mv '"
+      OUT2="$(cd "$P" && STUB_LOG="$WORK/log" bash ./bin/test-scratch.sh -- x 2>&1)"; RC=$?
+      [ "$RC" -eq 3 ] && ok "[$W] M1: test-scratch refuses the copy" || bad "[$W] M1: test-scratch rc $RC: $(printf '%s' "$OUT2" | tail -2)"
+      has "[$W] M1: test-scratch names the recovery command" "$OUT2" "--recover-promote"
+    fi
+    OUT="$(run "$P" --recover-promote)"; RC1=$?
+    OUT2="$(run "$P" --recover-promote)"; RC2=$?
+    [ "$RC1" -eq 0 ] && [ "$RC2" -eq 0 ] && ok "[$W] recovery rc 0, twice" || bad "[$W] recovery rc $RC1 then $RC2: $(printf '%s' "$OUT" | tail -2)"
+    has "[$W] the second run is a no-op" "$OUT2" "Nothing to recover"
+    F="$(fp "$M")"
+    case "$W" in committed|cleanup) EXP="$PROMOTED"; WHAT="promoted" ;; *) EXP="$B"; WHAT="pre-exec" ;; esac
+    [ "$F" = "$EXP" ] && ok "[$W] live model byte-identical to the $WHAT model" \
+      || bad "[$W] live model is $([ "$F" = "$B" ] && echo 'the pre-exec model' || { [ "$F" = "$PROMOTED" ] && echo 'the promoted model' || echo 'A MIX'; }), expected $WHAT"
+    [ -z "$(find "$M" -name '*mxtk-promote*' 2>/dev/null)" ] && ok "[$W] no leftovers anywhere" || bad "[$W] leftovers: $(find "$M" -name '*mxtk-promote*')"
+  done
+  OUT="$(run "$WORK/$LAYOUT-kill-mprcontents" mdlsource/test.mdl)"; RC=$?
+  [ "$RC" -eq 0 ] && ok "default exec runs again after the recovery" || bad "rc $RC after recovery: $(printf '%s' "$OUT" | tail -3)"
+  K="$(ls -d "$WORK/$LAYOUT-kill-mpr/.mpr-snapshots/.on-copy/"*/ 2>/dev/null | head -1)"
+  [ -n "$K" ] && grep -q 'changed by exec' "$K/model/Fixture.mpr" && [ -f "$K/model/mprcontents/cd/new.mxunit" ] \
+    && ok "the kept copy is whole after a rollback by --recover-promote" || bad "kept copy incomplete after the recovery"
 
-  echo "-- M2: only staged leftovers — live intact, delete them"
-  P="$WORK/$LAYOUT-staged"; mkproj "$P" "$SUB"; M="$P${SUB:+/$SUB}"
+  echo "-- leftovers without a manifest: ambiguous, nothing touched"
+  P="$WORK/$LAYOUT-nomanifest"; mkproj "$P" "$SUB"; M="$P${SUB:+/$SUB}"
   mkdir "$M/.mxtk-promote.999.mprcontents"; printf 'x\n' > "$M/.mxtk-promote.999.mpr"
-  OUT="$(run "$P" mdlsource/test.mdl)"; RC=$?
-  [ "$RC" -eq 1 ] && ok "refused (rc 1)" || bad "rc $RC"
-  has "M2: says the live model is intact" "$OUT" "the live model is intact"
-  hasnt "M2: no rename-back for staged-only" "$OUT" "mv '"
+  OUT="$(run "$P" --recover-promote)"; RC=$?
+  [ "$RC" -eq 2 ] && ok "recovery refuses (rc 2)" || bad "rc $RC"
+  has "and says why" "$OUT" "cannot tell what it is"
+  [ -d "$M/.mxtk-promote.999.mprcontents" ] && [ -f "$M/.mxtk-promote.999.mpr" ] && ok "nothing touched" || bad "ambiguous leftovers were touched"
+
+  echo "-- a side file written with an archive mtime is still promoted (by checksum)"
+  P="$WORK/$LAYOUT-archmtime"; mkproj "$P" "$SUB"; M="$P${SUB:+/$SUB}"
+  OUT="$(STUB_OLDMTIME=1 run "$P" --on-copy mdlsource/test.mdl)"; RC=$?
+  [ "$RC" -eq 0 ] && grep -q 'class Arch' "$M/javasource/m/Arch.java" 2>/dev/null && ok "Arch.java (mtime 2000) promoted" || bad "archive-mtime file not promoted (rc $RC)"
 
   echo "-- M3: a side file changed live during the exec"
   P="$WORK/$LAYOUT-sidechg"; mkproj "$P" "$SUB"; M="$P${SUB:+/$SUB}"
@@ -309,14 +321,6 @@ OUT="$(EXEC_ON_COPY=1 run "$P" --patch mdlsource/p.sh)"; RC=$?
 has "EXEC_ON_COPY with --patch: note" "$OUT" "does not apply to --patch"
 grep -q patched "$P/Fixture.mpr" && ok "patch ran on the live model" || bad "patch did not run (rc $RC): $(printf '%s' "$OUT" | tail -4)"
 
-echo "-- leftovers of an interrupted promotion refuse"
-P="$WORK/left"; mkproj "$P" ""
-mkdir "$P/.mxtk-promote.999.mprcontents"
-OUT="$(run "$P" --on-copy mdlsource/test.mdl)"; RC=$?
-[ "$RC" -eq 1 ] && ok "refused rc 1" || bad "rc $RC"
-has "names restore-mpr" "$OUT" "restore-mpr.sh"
-[ ! -f "$WORK/log/exec-targets" ] && ok "nothing executed" || bad "exec ran"
-
 echo ""
 echo "== $PASS passed, $FAIL failed"
 [ "$FAIL" -eq 0 ]

From fff1cd57db14ce5d5d25e16a4beb60a2a0e95517 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 14 Oct 2026 16:52:42 +0000
Subject: [PATCH 4/7] =?UTF-8?q?fix(exec):=20#384=20attack=20review=20?=
 =?UTF-8?q?=E2=80=94=20lone=20.committed=20recovers;=20recovery=20refuses?=
 =?UTF-8?q?=20under=20SP?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- mxtk_promote_recover: a lone .mxtk-promote.N.committed (kill between the
  committed cleanup's manifest rm and its marker rm) is removed like .fsprobe
  and .trash instead of returning 2 forever and blocking every exec.
- exec.sh --recover-promote refuses while Studio Pro holds the model, even
  under FORCE_EXEC, as --on-copy does.
- skill note: after a kill, run --recover-promote before editing.
Fixture: +12 checks (lone .committed recovered then exec runs; recovery under
SP with FORCE_EXEC refused, nothing touched).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 project-bin/_common.sh           |  6 ++++--
 project-bin/exec.sh              |  4 ++--
 skills/iterative-build-loop.md   |  2 +-
 tests/wave2/test-exec-on-copy.sh | 20 ++++++++++++++++++++
 4 files changed, 27 insertions(+), 5 deletions(-)

diff --git a/project-bin/_common.sh b/project-bin/_common.sh
index 4dbfe1df..96ef7eb8 100755
--- a/project-bin/_common.sh
+++ b/project-bin/_common.sh
@@ -711,11 +711,13 @@ mxtk_promote_recover() {
   if [ ! -f "$t.manifest" ]; then
     for f in "$t".*; do
       [ -e "$f" ] || continue
-      case "$f" in "$t.fsprobe"|"$t.trash") ;; *)
+      # .committed alone: a kill between the committed cleanup's two last rms (manifest first) —
+      # the promotion was complete, only its marker is left.
+      case "$f" in "$t.fsprobe"|"$t.trash"|"$t.committed") ;; *)
         echo "✗ promotion $p: $f exists but its manifest does not — cannot tell what it is. Nothing touched."
         return 2 ;; esac
     done
-    rm -rf "${t:?}.fsprobe" "${t:?}.trash"; return 0
+    rm -rf "${t:?}.fsprobe" "${t:?}.trash" "${t:?}.committed"; return 0
   fi
   if [ -f "$t.committed" ]; then
     rm -rf "${t:?}.old.mprcontents" "${t:?}.old.mpr" "${t:?}.trash" || return 1
diff --git a/project-bin/exec.sh b/project-bin/exec.sh
index da6d6dd9..a06eb056 100755
--- a/project-bin/exec.sh
+++ b/project-bin/exec.sh
@@ -548,8 +548,8 @@ if sp_holds_model; then
   SP_OPEN=1
   echo "✗ Studio Pro has $NAME open (lock PID $SP_PID alive) — refusing exec (split-brain corruption risk)."
   echo "  → Close the project in Studio Pro (or quit SP), then re-run."
-  if [ "$ON_COPY" = 1 ]; then
-    echo "    --on-copy: FORCE_EXEC does not override this — a promotion is refused while Studio Pro holds the model."
+  if [ "$ON_COPY" = 1 ] || [ "$RECOVER" = 1 ]; then
+    echo "    --on-copy / --recover-promote: FORCE_EXEC does not override this — a promotion is refused while Studio Pro holds the model."
     exit 1
   fi
   echo "    Override (NOT recommended): FORCE_EXEC=1 ./bin/exec.sh $SCRIPT"
diff --git a/skills/iterative-build-loop.md b/skills/iterative-build-loop.md
index 9dc02f3c..bf358548 100644
--- a/skills/iterative-build-loop.md
+++ b/skills/iterative-build-loop.md
@@ -293,7 +293,7 @@ is the part worth stating twice.
 | `last-mxbuild-errors.json` is cleared at the **start** of a run, not on success | An interrupted run must not leave a previous failure's file looking like its own report |
 | Studio Pro is never auto-killed; the reopen is offered, then done on a yes | See the SP Lifecycle Rule above |
 
-**Opt-in: `./bin/exec.sh --on-copy <script>` (or `EXEC_ON_COPY=1`).** By default the live model holds the script's unverified write for the length of the gate, and keeps it if exec.sh is killed. With `--on-copy`, `mxcli exec` and the mxbuild gate run on a scratch copy under the same lock. The live model is written only by a rename-based promotion after a verified pass with exit 0. Promotion is refused while Studio Pro holds the model (even under `FORCE_EXEC`) and when the live model changed since the copy was taken. On any refusal or failure the live model is byte-identical and the copy is kept under `.mpr-snapshots/.on-copy/`, with a resume hint. On a single-tree checkout only the `.mpr` and the app directories are copied (`MXTK_APP_DIRS` in `_common.sh`), never `sources/`, `analysis/`, `docs/` or binaries. If a promotion is killed half-way, every exec and `test-scratch.sh` refuses until `./bin/exec.sh --recover-promote` has finished it or renamed it back; it is safe to run twice. It is stub-tested only and not yet the default (toolkit #350).
+**Opt-in: `./bin/exec.sh --on-copy <script>` (or `EXEC_ON_COPY=1`).** By default the live model holds the script's unverified write for the length of the gate, and keeps it if exec.sh is killed. With `--on-copy`, `mxcli exec` and the mxbuild gate run on a scratch copy under the same lock. The live model is written only by a rename-based promotion after a verified pass with exit 0. Promotion is refused while Studio Pro holds the model (even under `FORCE_EXEC`) and when the live model changed since the copy was taken. On any refusal or failure the live model is byte-identical and the copy is kept under `.mpr-snapshots/.on-copy/`, with a resume hint. On a single-tree checkout only the `.mpr` and the app directories are copied (`MXTK_APP_DIRS` in `_common.sh`), never `sources/`, `analysis/`, `docs/` or binaries. If a promotion is killed half-way, every exec and `test-scratch.sh` refuses until `./bin/exec.sh --recover-promote` has finished it or renamed it back; it is safe to run twice. After such a kill, run `--recover-promote` before editing anything. It is stub-tested only and not yet the default (toolkit #350).
 
 ### Standalone SP restart — `bin/restart-sp.sh`
 
diff --git a/tests/wave2/test-exec-on-copy.sh b/tests/wave2/test-exec-on-copy.sh
index 64a4783b..63ebe478 100755
--- a/tests/wave2/test-exec-on-copy.sh
+++ b/tests/wave2/test-exec-on-copy.sh
@@ -251,6 +251,26 @@ for LAYOUT in root app; do
   has "and says why" "$OUT" "cannot tell what it is"
   [ -d "$M/.mxtk-promote.999.mprcontents" ] && [ -f "$M/.mxtk-promote.999.mpr" ] && ok "nothing touched" || bad "ambiguous leftovers were touched"
 
+  echo "-- a lone .committed (kill between the cleanup's last two rms) is recovered, then exec runs"
+  P="$WORK/$LAYOUT-lonecommit"; mkproj "$P" "$SUB"; M="$P${SUB:+/$SUB}"
+  : > "$M/.mxtk-promote.998.committed"
+  OUT="$(run "$P" mdlsource/test.mdl)"; RC=$?
+  [ "$RC" -eq 1 ] && ok "exec refuses over it first" || bad "rc $RC"
+  OUT="$(run "$P" --recover-promote)"; RC=$?
+  [ "$RC" -eq 0 ] && [ ! -e "$M/.mxtk-promote.998.committed" ] && ok "recovery removes it (rc 0)" || bad "rc $RC: $(printf '%s' "$OUT" | tail -2)"
+  OUT="$(run "$P" mdlsource/test.mdl)"; RC=$?
+  [ "$RC" -eq 0 ] && ok "the next exec runs" || bad "next exec rc $RC: $(printf '%s' "$OUT" | tail -2)"
+
+  echo "-- --recover-promote refuses while Studio Pro holds the model, FORCE_EXEC or not"
+  P="$WORK/$LAYOUT-recsp"; mkproj "$P" "$SUB"; M="$P${SUB:+/$SUB}"
+  : > "$M/.mxtk-promote.997.committed"
+  sleep 60 & SPP=$!; BG="$BG $SPP"; printf '{"ProcessId":%s}\n' "$SPP" > "$M/Fixture.mpr.lock"
+  OUT="$(FORCE_EXEC=1 run "$P" --recover-promote)"; RC=$?
+  [ "$RC" -eq 1 ] && ok "refused (rc 1)" || bad "rc $RC"
+  has "says FORCE_EXEC does not override" "$OUT" "FORCE_EXEC does not override"
+  [ -e "$M/.mxtk-promote.997.committed" ] && ok "nothing touched" || bad "recovery ran while SP held the model"
+  kill "$SPP" 2>/dev/null; rm -f "$M/Fixture.mpr.lock"
+
   echo "-- a side file written with an archive mtime is still promoted (by checksum)"
   P="$WORK/$LAYOUT-archmtime"; mkproj "$P" "$SUB"; M="$P${SUB:+/$SUB}"
   OUT="$(STUB_OLDMTIME=1 run "$P" --on-copy mdlsource/test.mdl)"; RC=$?

From a463e69bf04dd9385c6d320f76f28a7e0f8ceebb Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 15 Oct 2026 04:51:11 +0000
Subject: [PATCH 5/7] =?UTF-8?q?fix(exec):=20#390=20field=20run=20=E2=80=94?=
 =?UTF-8?q?=20copy=20cost,=20Studio=20Pro=20refusal=20row,=20recover=20ski?=
 =?UTF-8?q?ps=20scan?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Field run #390 (macOS, 549 units): a and b PASS, Ctrl-C half not run. It
found the copy dominating (87-134 s against a ~120 ms swap).
- mxtk_copy_model_tree: on-copy entries are cloned where the filesystem can
  (macOS `cp -c`, Linux reflink; probed read-only on the .mpr, MXTK_COPY_MODE
  overrides), else tarred; build caches (MXTK_COPY_SKIP: node_modules, .cache,
  .mendix-cache, .gradle) are never copied. A two-tree app/ uses the same path
  (--app).
- side-file manifest: one batched cksum, caches pruned (was a process per file);
  the outside-write listing prunes caches too.
- Bench (550 units + realistic app tree, BENCH_APP_TREE=1): on-copy overhead
  per exec +79.5 s -> +1.7 s; kill-window results unchanged.
- A Studio Pro refusal under --on-copy / --recover-promote writes a
  "🚫 blocked (Studio Pro holds the model)" BUILD-LOG row. The Studio Pro guard
  already runs before the uncommitted-model guard on every path; a fixture now
  proves it with a dirty model.
- --recover-promote skips the STOP-row scan (there is no script).

Fixture test-exec-on-copy: 283 checks (copy modes clone/tar, caches, mtimes,
SP row, dirty + SP order).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 CHANGELOG.md                      |  2 +-
 project-bin/_common.sh            | 71 +++++++++++++++++++++++--------
 project-bin/exec.sh               | 16 ++++---
 skills/iterative-build-loop.md    |  2 +-
 tests/wave2/bench-exec-on-copy.sh | 19 +++++++++
 tests/wave2/test-exec-on-copy.sh  | 28 ++++++++++++
 6 files changed, 112 insertions(+), 26 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 425001d9..b9bd7eba 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,7 +19,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are. Named m
 
 ## Unreleased
 
-- new(exec): **`exec.sh --on-copy` (or `EXEC_ON_COPY=1`), opt-in: the script and the mxbuild gate run on a scratch copy, and the live model is written only by a rename-based promotion after a verified pass** ([#350](https://github.com/MendixMau/mxcli-project-toolkit/issues/350)). By default the live model holds an unverified write for the length of the gate (22-65 s per apply in the field), and keeps it when exec.sh is killed. Promotion is refused while Studio Pro holds the model (even under `FORCE_EXEC`), when the live model changed since the copy (cksum manifest), or when the copy is on another filesystem. A swap that fails part-way renames back, else restores the snapshot. On any other outcome the live model is untouched and the copy is kept under `.mpr-snapshots/.on-copy/` with a resume hint (newest 3 kept). Files exec writes beside the model (javasource/, javascriptsource/, theme/...; found by checksum) are promoted with it only if their live copy still matches its pre-copy checksum; a write anywhere else refuses. A single-tree checkout copies only the `.mpr` and the app directories, never sources/, analysis/, docs/ or binaries. A promotion killed half-way leaves `.mxtk-promote.*` names: every exec.sh path (the default one included) and `test-scratch.sh` then refuse until `./bin/exec.sh --recover-promote` finishes a committed promotion or renames the live model back (idempotent; a commit marker decides which; `restore-mpr.sh` only as the last resort). The default path is otherwise unchanged. The copy routine moved from `test-scratch.sh` into `_common.sh` (`mxtk_copy_model_tree`, `mxtk_promote_leftovers`). Fixture `tests/wave2/test-exec-on-copy.sh` (241 checks, both layouts; a kill in each of 8 promotion windows, recovered twice, is the pre-exec or the promoted model, never a mix). Bench `tests/wave2/bench-exec-on-copy.sh` (stub mxbuild 2 s, an input): with exec.sh killed mid-gate the live model stayed byte-identical in 0/10 default runs and 10/10 on-copy runs at 500, 5,000 and 20,000 units. The broken window fell from about 2.1 s (clean) and 5.5-25.4 s (failed gate) to a 15-42 ms swap, at a cost of +1.4 s, +3.7 s and +10.9 s wall time per exec. Field evidence: none yet (stub-only); a field run with Studio Pro closed and then open is owed before it can become the default. Statement-level resume from the kept copy is a follow-up. — external review (#350), MendixMau
+- new(exec): **`exec.sh --on-copy` (or `EXEC_ON_COPY=1`), opt-in: the script and the mxbuild gate run on a scratch copy, and the live model is written only by a rename-based promotion after a verified pass** ([#350](https://github.com/MendixMau/mxcli-project-toolkit/issues/350)). By default the live model holds an unverified write for the length of the gate (22-65 s per apply in the field), and keeps it when exec.sh is killed. Promotion is refused while Studio Pro holds the model (even under `FORCE_EXEC`), when the live model changed since the copy (cksum manifest), or when the copy is on another filesystem. A swap that fails part-way renames back, else restores the snapshot. On any other outcome the live model is untouched and the copy is kept under `.mpr-snapshots/.on-copy/` with a resume hint (newest 3 kept). Files exec writes beside the model (javasource/, javascriptsource/, theme/...; found by checksum) are promoted with it only if their live copy still matches its pre-copy checksum; a write anywhere else refuses. A single-tree checkout copies only the `.mpr` and the app directories, never sources/, analysis/, docs/ or binaries. A promotion killed half-way leaves `.mxtk-promote.*` names: every exec.sh path (the default one included) and `test-scratch.sh` then refuse until `./bin/exec.sh --recover-promote` finishes a committed promotion or renames the live model back (idempotent; a commit marker decides which; `restore-mpr.sh` only as the last resort). The default path is otherwise unchanged. The copy routine moved from `test-scratch.sh` into `_common.sh` (`mxtk_copy_model_tree`, `mxtk_promote_leftovers`). Fixture `tests/wave2/test-exec-on-copy.sh` (241 checks, both layouts; a kill in each of 8 promotion windows, recovered twice, is the pre-exec or the promoted model, never a mix). Bench `tests/wave2/bench-exec-on-copy.sh` (stub mxbuild 2 s, an input): with exec.sh killed mid-gate the live model stayed byte-identical in 0/10 default runs and 10/10 on-copy runs at 500, 5,000 and 20,000 units. The broken window fell from about 2.1 s (clean) and 5.5-25.4 s (failed gate) to a 15-42 ms swap, at a cost of +1.4 s, +3.7 s and +10.9 s wall time per exec. Field run ([#390](https://github.com/MendixMau/mxcli-project-toolkit/issues/390), macOS arm64, Mendix 11.15, 549 units): promotion with Studio Pro closed and the Studio Pro refusal both PASS; the Ctrl-C recovery half was not run. It found the copy dominating (87-134 s against a ~120 ms swap): the copy now clones where the filesystem can (APFS `cp -c`, Linux reflink), never copies build caches (`node_modules`, `.cache`), and checksums side files in one batch; on the bench (550 units plus a realistic app tree: 15,000-file node_modules, 250 MB of jars and widgets) the on-copy overhead fell from +79.5 s to +1.7 s per exec. A Studio Pro refusal under `--on-copy` / `--recover-promote` now writes a BUILD-LOG row. Statement-level resume from the kept copy is a follow-up. — external review (#350), MendixMau
 - new(tests/behaviour): **a standing behaviour suite for agent-read text: arms M (base ref), T (candidate ref, or the base minus one skill for an ablation) and N (no pack), two drafting tasks with planted STOP-row requests and five retrieval probes, scored mechanically.** `tests/behaviour/build-packs.sh` builds a pack from any ref in a temporary worktree; `score.sh` adds `read_all` (the agent quoted the pack's `PACK-END` line back), `tool_calls` and `tokens`, and treats `mxcli check` as optional (NA without a binary). `RUNBOOK.md` has the triggers (every PR that changes baseline-routed text or an agent stub; N and ablations at each release cut), 5 reps x 2 tasks plus 5 probes x 3 reps, the rule (T no worse than M on every scored metric, probes T >= M - 1), and partial reads counted and re-run, never dropped. `docs/RELEASE-PROCESS.md` §4a names it as the way to run the Behaviour A/B. Field runs committed under `tests/behaviour/results/`: the 2026-10-15 stub-diet A/B (#369/#378/#380, 42 reps, 3 partial reads on the 4,822-line pack) and the first no-pack run (page trap refused 0/5 without a pack against 5/5 with either; mf passes check 1/5 against 5/5; every arm, N included, also inherited the host session's project CLAUDE.md (a generic mxcli/MDL guide), so N measures 'no toolkit rules', not 'no guidance'). Golden input: four real agent outputs, `tests/wave2/test-behaviour-score.sh`. — maintainer request (MendixMau)
 - process(pr-template, release-process): **every Direct-lane PR and every review fills a five-row Impact block: Process, Dependencies, Context cost, Behaviour, Runtime.** "none" or "NOT RUN: <reason>" is legal, a blank row is not. Context cost is pasted from `bin/render-routing.sh --check` on base and head, never estimated; a missing or estimated row is a review finding. The Behaviour A/B (`process/preflight-skill-baseline-2026-08-31.md`) is required for baseline-routed text and agent stubs, recommended for situational skills, NOT RUN with a reason for process docs review agents read, n/a for scripts only; Context cost may be "none" when no routed or always-loaded file is touched. `docs/RELEASE-PROCESS.md` §4a holds the rule and a bad/good example; `CONTRIBUTING.md`'s reviewer list points there. No CI check: `bin/check-pr-discipline.sh` reads the git diff, not the PR body. Field evidence: three PRs reviewed on 2026-10-15 with no process cost stated (#375 added a human step per re-baseline, #384 adds 1–11 s per exec), both found by chance. — maintainer request, MendixMau
 - learn(learned-detection-gaps, testing-shape, ui-loop): **a class on a snippet call never reaches the DOM; a 403 bounce and a widget-pinned session probe both read as sign-outs; app restarts matched a "signs me out" report by timing.** Detection-gaps row: `Class` on a `SNIPPETCALL` is green through check, exec, mxbuild, lint and DESCRIBE, and absent in the browser ([#336](https://github.com/MendixMau/mxcli-project-toolkit/issues/336)). Testing-shape §4 gains two false-red rows: `login.html?messageCode=403` with the session kept ([#338](https://github.com/MendixMau/mxcli-project-toolkit/issues/338)), and instruments pinned to one grid name or a typed menu list (1/7 and 7/34 false FAILs after a redesign, [#339](https://github.com/MendixMau/mxcli-project-toolkit/issues/339)). ui-loop: say so before a restart while a human uses the app ([#337](https://github.com/MendixMau/mxcli-project-toolkit/issues/337)) — three-app field run, 2026-10-14
diff --git a/project-bin/_common.sh b/project-bin/_common.sh
index 7d1d57ab..3848d7e1 100755
--- a/project-bin/_common.sh
+++ b/project-bin/_common.sh
@@ -658,30 +658,67 @@ mxtk_mxbuild_why() {
   "$_py" -c "import json;d=json.load(open('$(native_path "$1")'));print('; '.join((e.get('message','') if isinstance(e,dict) else str(e)) for e in d.get('errors',[]) or [])[:300])" 2>/dev/null || true
 }
 
-# mxtk_copy_model_tree <model-dir> <dest-dir> [<mpr-basename>] — copy the model tree into an
-# existing <dest-dir>, for a scratch copy.
-#   Two args: the whole <model-dir> (the .mpr, mprcontents/ and everything mxbuild reads beside
-#   them), leaving out .git, .mpr-snapshots, deployment, .mxcli (the LIVE app's run --local record
-#   — a copy carrying it points app-restart.sh at the live app) and node_modules.
-#   Three args: an ALLOW-LIST — <mpr-basename> with its -wal/-shm if present, plus the app
-#   directories in $MXTK_APP_DIRS that exist. For a single-tree checkout, where <model-dir> is the
-#   repo root and also holds sources/, analysis/, docs/ and binaries nobody's build reads. A
-#   directory mxbuild needs and the list lacks makes the gate fail ON THE COPY — never the live
-#   model — and MXTK_APP_DIRS adds it.
-# Used by bin/test-scratch.sh (mxcli test, #278; two args) and bin/exec.sh --on-copy (#350). tar
-# preserves mtimes, which --on-copy relies on to tell the files `mxcli exec` wrote from the files
-# it copied. Returns tar's status.
+# mxtk_copy_model_tree <model-dir> <dest-dir> [<mpr-basename> | --app] — copy the model tree into
+# an existing <dest-dir>, for a scratch copy.
+#   Two args (bin/test-scratch.sh, #278): the whole <model-dir> through tar, leaving out .git,
+#   .mpr-snapshots, deployment, .mxcli (the LIVE app's run --local record — a copy carrying it
+#   points app-restart.sh at the live app) and node_modules.
+#   <mpr-basename> (bin/exec.sh --on-copy on a single-tree checkout, #350): an ALLOW-LIST — the .mpr
+#   with its -wal/-shm, plus the directories in $MXTK_APP_DIRS that exist; never sources/,
+#   analysis/, docs/ or binaries. A directory mxbuild needs and the list lacks fails the gate ON THE
+#   COPY, never the live model; MXTK_APP_DIRS adds it.
+#   --app (exec.sh --on-copy on a two-tree app/): every top-level entry but the two-arg exclusions.
+#   In both on-copy forms, directories named in $MXTK_COPY_SKIP (build caches) are never copied,
+#   and an entry is CLONED where the filesystem can (macOS APFS `cp -c`, Linux reflink), else tarred.
+#   WHY (field run, #390): a 549-unit app took 87-134 s to copy against a ~120 ms swap. Clone vs tar
+#   is probed once per copy on the .mpr itself (read-only); MXTK_COPY_MODE=tar|clone overrides.
+#   Every path preserves mtimes, which --on-copy relies on. Returns non-zero if any entry failed.
 MXTK_APP_DIRS="${MXTK_APP_DIRS:-mprcontents widgets javasource javascriptsource theme themesource userlib vendorlib resources nativemobile mlsource}"
+MXTK_COPY_SKIP="${MXTK_COPY_SKIP:-node_modules .cache .mendix-cache .gradle}"
+mxtk_copy_how() {  # $1 = a file in the source, $2 = dest dir: prints clone-mac | clone-gnu | tar
+  case "${MXTK_COPY_MODE:-}" in
+    tar) echo tar; return ;;
+    clone) [ "$(mxtk_platform)" = macos ] && echo clone-mac || echo clone-gnu; return ;;
+  esac
+  if [ "$(mxtk_platform)" = macos ] && cp -c "$1" "$2/.mxtk-cowprobe" 2>/dev/null; then echo clone-mac
+  elif cp --reflink=always "$1" "$2/.mxtk-cowprobe" 2>/dev/null; then echo clone-gnu
+  else echo tar; fi
+  rm -f "${2:?}/.mxtk-cowprobe"
+}
 mxtk_copy_model_tree() {
   if [ -z "${3:-}" ]; then
     tar -C "$1" --exclude=./.git --exclude=./.mpr-snapshots --exclude=./deployment \
         --exclude=./.mxcli --exclude=./node_modules -cf - . | tar -C "$2" -xf -
     return
   fi
-  local _src="$1" _dst="$2" _mb="$3" _e
-  set --
-  for _e in "$_mb" "$_mb-wal" "$_mb-shm" $MXTK_APP_DIRS; do [ -e "$_src/$_e" ] && set -- "$@" "./$_e"; done
-  tar -C "$_src" --exclude=node_modules -cf - "$@" | tar -C "$_dst" -xf -
+  local _src="$1" _dst="$2" _e _how _x="" _s _skip _rc=0 _list
+  for _s in $MXTK_COPY_SKIP; do _x="$_x --exclude=$_s"; done
+  if [ "$3" = --app ]; then
+    _list="$(ls -A "$_src" | grep -vxE '\.git|\.mpr-snapshots|deployment|\.mxcli|node_modules')"
+    _how="$(mxtk_copy_how "$_src/$(ls "$_src" | grep -m1 '\.mpr$')" "$_dst")"
+  else
+    _list="$(for _e in "$3" "$3-wal" "$3-shm" $MXTK_APP_DIRS; do [ -e "$_src/$_e" ] && echo "$_e"; done)"
+    _how="$(mxtk_copy_how "$_src/$3" "$_dst")"
+  fi
+  while IFS= read -r _e; do
+    [ -n "$_e" ] || continue
+    _skip=""   # an entry holding a build cache is tarred (with the cache excluded), never cloned
+    if [ -d "$_src/$_e" ] && [ "$_how" != tar ]; then
+      for _s in $MXTK_COPY_SKIP; do [ -n "$(find "$_src/$_e" -name "$_s" -prune -print 2>/dev/null | head -1)" ] && _skip=1; done
+    fi
+    case "$_how${_skip:+-skip}" in
+      clone-mac) cp -cRp "$_src/$_e" "$_dst/$_e" ;;
+      clone-gnu) cp -a --reflink=auto "$_src/$_e" "$_dst/$_e" ;;
+      *) false ;;
+    esac || {
+      rm -rf "${_dst:?}/${_e:?}"
+      # shellcheck disable=SC2086
+      tar -C "$_src" $_x -cf - "./$_e" | tar -C "$_dst" -xf - || _rc=1
+    }
+  done <<MXTKLIST
+$_list
+MXTKLIST
+  return "$_rc"
 }
 
 # ── Interrupted exec.sh --on-copy promotions (#350, #384 review) ─────────────────────────────
diff --git a/project-bin/exec.sh b/project-bin/exec.sh
index 4f9f664e..fefcd5d2 100755
--- a/project-bin/exec.sh
+++ b/project-bin/exec.sh
@@ -537,7 +537,7 @@ take_score() {
 # Not found, or the scan itself errors (exit 2) → one warning, and the exec goes on: mxcli
 # check and the mxbuild gate still stand behind it.
 SCAN_NOTE=""
-if [ "$PATCH_MODE" != "1" ]; then
+if [ "$PATCH_MODE" != "1" ] && [ "$RECOVER" != 1 ]; then
   _SCAN=""
   for _s in "${MXTK_ROOT:-}/bin/mdl-scan.sh" \
             "$(sed -nE 's/^\| *Toolkit root *\| *`([^`]+)`.*/\1/p' "$PROJECT_ROOT/CLAUDE.local.md" 2>/dev/null | head -1)/bin/mdl-scan.sh"; do
@@ -605,6 +605,7 @@ if sp_holds_model; then
   echo "  → Close the project in Studio Pro (or quit SP), then re-run."
   if [ "$ON_COPY" = 1 ] || [ "$RECOVER" = 1 ]; then
     echo "    --on-copy / --recover-promote: FORCE_EXEC does not override this — a promotion is refused while Studio Pro holds the model."
+    log_build "🚫 blocked (Studio Pro holds the model)" "lock PID $SP_PID — nothing written"
     exit 1
   fi
   echo "    Override (NOT recommended): FORCE_EXEC=1 ./bin/exec.sh $SCRIPT"
@@ -1103,9 +1104,9 @@ oc_fingerprint() {  # $1 = model dir. One cksum over the .mpr, its -wal, and eve
   ( cd "$1" && { cksum "$MPR_BASE"; [ -f "$MPR_BASE-wal" ] && cksum "$MPR_BASE-wal"
       if [ -d mprcontents ]; then find mprcontents -type f | LC_ALL=C sort | tr '\n' '\0' | xargs -0 cksum; fi; } ) 2>/dev/null | cksum
 }
-oc_side_manifest() {  # $1 = model dir: "crc size path" per file under $OC_SIDE_DIRS
-  ( cd "$1" && for _d in $OC_SIDE_DIRS; do [ -d "$_d" ] && find "$_d" -type f; done | LC_ALL=C sort \
-      | while IFS= read -r _f; do cksum "$_f"; done ) 2>/dev/null
+oc_side_manifest() {  # $1 = model dir: "crc size path" per file under $OC_SIDE_DIRS, build caches pruned
+  ( cd "$1" && for _d in $OC_SIDE_DIRS; do [ -d "$_d" ] && find "$_d" \( -name node_modules -o -name .cache \) -prune \
+      -o -type f -print; done | LC_ALL=C sort | tr '\n' '\0' | xargs -0 cksum | awk 'NF >= 3' ) 2>/dev/null
 }
 oc_side_sum() {  # $1 = file: "crc size", or "-" when it does not exist
   if [ -f "$1" ]; then cksum < "$1" | awk '{print $1, $2}'; else echo "-"; fi
@@ -1115,7 +1116,7 @@ oc_side_sum0() {  # $1 = rel path: its "crc size" in OC_SIDE0 (taken before the
 }
 oc_other_list() {  # $1 = copy [$2 = marker: only files newer]: sorted paths outside the model and $OC_SIDE_DIRS
   ( cd "$1" && find . \( -path ./mprcontents -o -path ./deployment -o -path ./.mxcli -o -path ./.git \
-      -o -path ./node_modules \) -prune -o -type f ${2:+-newer "$2"} -print 2>/dev/null | sed 's|^\./||' | while IFS= read -r _r; do
+      -o -name node_modules -o -name .cache \) -prune -o -type f ${2:+-newer "$2"} -print 2>/dev/null | sed 's|^\./||' | while IFS= read -r _r; do
       case "$_r" in "$MPR_BASE"|"$MPR_BASE".*|"$MPR_BASE"-*) continue ;; esac
       _in=0; for _d in $OC_SIDE_DIRS; do case "$_r" in "$_d"/*) _in=1 ;; esac; done
       [ "$_in" = 1 ] || printf '%s\n' "$_r"
@@ -1264,10 +1265,11 @@ if [ "$ON_COPY" = 1 ]; then
   _c0=$(oc_ms)
   # Single-tree checkout (the model dir is the repo root): copy the allow-list only — the .mpr and
   # the app directories (_common.sh MXTK_APP_DIRS), never sources/, analysis/, docs/ or binaries.
-  # A two-tree app/ is all app, and is copied whole.
+  # A two-tree app/ is all app, and is copied whole. Never build caches (MXTK_COPY_SKIP); cloned
+  # where the filesystem can (field run #390: a 549-unit app took 87-134 s by tar on macOS).
   _oc_rc=0
   if [ "$MODEL_DIR" = "$(cd "$PROJECT_ROOT" && pwd)" ]; then mxtk_copy_model_tree "$MODEL_DIR" "$OC_COPY" "$MPR_BASE" || _oc_rc=$?
-  else mxtk_copy_model_tree "$MODEL_DIR" "$OC_COPY" || _oc_rc=$?; fi
+  else mxtk_copy_model_tree "$MODEL_DIR" "$OC_COPY" --app || _oc_rc=$?; fi
   if [ "$_oc_rc" -ne 0 ] || [ ! -f "$OC_MPR" ]; then
     rm -rf "${OC_SCR:?}"
     echo "✗ --on-copy: copying the model to $OC_SCR failed — nothing was written."
diff --git a/skills/iterative-build-loop.md b/skills/iterative-build-loop.md
index bf358548..8bce1b41 100644
--- a/skills/iterative-build-loop.md
+++ b/skills/iterative-build-loop.md
@@ -293,7 +293,7 @@ is the part worth stating twice.
 | `last-mxbuild-errors.json` is cleared at the **start** of a run, not on success | An interrupted run must not leave a previous failure's file looking like its own report |
 | Studio Pro is never auto-killed; the reopen is offered, then done on a yes | See the SP Lifecycle Rule above |
 
-**Opt-in: `./bin/exec.sh --on-copy <script>` (or `EXEC_ON_COPY=1`).** By default the live model holds the script's unverified write for the length of the gate, and keeps it if exec.sh is killed. With `--on-copy`, `mxcli exec` and the mxbuild gate run on a scratch copy under the same lock. The live model is written only by a rename-based promotion after a verified pass with exit 0. Promotion is refused while Studio Pro holds the model (even under `FORCE_EXEC`) and when the live model changed since the copy was taken. On any refusal or failure the live model is byte-identical and the copy is kept under `.mpr-snapshots/.on-copy/`, with a resume hint. On a single-tree checkout only the `.mpr` and the app directories are copied (`MXTK_APP_DIRS` in `_common.sh`), never `sources/`, `analysis/`, `docs/` or binaries. If a promotion is killed half-way, every exec and `test-scratch.sh` refuses until `./bin/exec.sh --recover-promote` has finished it or renamed it back; it is safe to run twice. After such a kill, run `--recover-promote` before editing anything. It is stub-tested only and not yet the default (toolkit #350).
+**Opt-in: `./bin/exec.sh --on-copy <script>` (or `EXEC_ON_COPY=1`).** By default the live model holds the script's unverified write for the length of the gate, and keeps it if exec.sh is killed. With `--on-copy`, `mxcli exec` and the mxbuild gate run on a scratch copy under the same lock. The live model is written only by a rename-based promotion after a verified pass with exit 0. Promotion is refused while Studio Pro holds the model (even under `FORCE_EXEC`) and when the live model changed since the copy was taken. On any refusal or failure the live model is byte-identical and the copy is kept under `.mpr-snapshots/.on-copy/`, with a resume hint. The copy is cloned where the filesystem allows and never includes build caches. On a single-tree checkout only the `.mpr` and the app directories are copied (`MXTK_APP_DIRS` in `_common.sh`), never `sources/`, `analysis/`, `docs/` or binaries. If a promotion is killed half-way, every exec and `test-scratch.sh` refuses until `./bin/exec.sh --recover-promote` has finished it or renamed it back; it is safe to run twice. After such a kill, run `--recover-promote` before editing anything. It is stub-tested only and not yet the default (toolkit #350).
 
 ### Standalone SP restart — `bin/restart-sp.sh`
 
diff --git a/tests/wave2/bench-exec-on-copy.sh b/tests/wave2/bench-exec-on-copy.sh
index cb747ca3..15e6e2a9 100755
--- a/tests/wave2/bench-exec-on-copy.sh
+++ b/tests/wave2/bench-exec-on-copy.sh
@@ -8,6 +8,10 @@
 #   BENCH_RUNS=3              clean runs per path per size (the median is reported)
 #   BENCH_FAIL_RUNS=10        failure-injection runs per path, per failure kind, per size
 #   BENCH_UNIT_BYTES=1024     bytes per synthetic unit
+#   BENCH_APP_TREE=1          also build a realistic app tree beside the model (field run #390:
+#                             the copy, not the swap, dominated): javasource 1,500 files,
+#                             javascriptsource 100 + a node_modules of 15,000, themesource 400,
+#                             theme 60, widgets 40 x 1 MB, userlib 60 x 1 MB, vendorlib 150 x 1 MB
 #
 # What it measures, per size, default path vs --on-copy, with the real exec.sh, snapshot-mpr.sh,
 # restore-mpr.sh and _common.sh and stub mxcli/mxbuild (no real model, mxcli or mxbuild):
@@ -31,6 +35,7 @@ SIZES="${BENCH_SIZES:-500 5000 20000}"
 RUNS="${BENCH_RUNS:-3}"
 FRUNS="${BENCH_FAIL_RUNS:-10}"
 UBYTES="${BENCH_UNIT_BYTES:-1024}"
+APPTREE="${BENCH_APP_TREE:-0}"
 case "$(date +%N)" in *[!0-9]*|'') echo "bench-exec-on-copy: needs GNU date (%N) for ms timing" >&2; exit 2 ;; esac
 ms() { echo $(( $(date +%s%N) / 1000000 )); }
 
@@ -58,6 +63,19 @@ printf '{"problems":[]}' > "$ef"; exit 0
 MXB
 chmod +x "$WORK/stubs/mxbuild"
 
+mkfiles() {  # $1 = dir, $2 = count, $3 = bytes, $4 = extension — one awk, not a process per file
+  mkdir -p "$1"
+  awk -v d="$1" -v n="$2" -v b="$3" -v e="$4" 'BEGIN { s = "x"; while (length(s) < b) s = s s; s = substr(s, 1, b)
+    for (i = 0; i < n; i++) { f = d "/f" i "." e; printf "%s", s > f; close(f) } }'
+}
+mkapptree() {  # $1 = template dir
+  local m p
+  for m in 1 2 3 4 5; do mkfiles "$1/javasource/m$m/proxies" 300 2048 java; mkfiles "$1/themesource/m$m/web" 80 1024 scss; done
+  mkfiles "$1/javascriptsource/m1/actions" 100 1024 js
+  for p in $(seq 1 300); do mkfiles "$1/javascriptsource/m1/actions/node_modules/pkg$p" 50 256 js; done
+  mkfiles "$1/theme/web" 60 2048 scss
+  mkfiles "$1/widgets" 40 1048576 mpk; mkfiles "$1/userlib" 60 1048576 jar; mkfiles "$1/vendorlib" 150 1048576 jar
+}
 mktemplate() {  # $1 = dir, $2 = unit count
   local T="$1" n="$2" i d pad
   mkdir -p "$T/bin" "$T/mdlsource" "$T/javasource/m"
@@ -71,6 +89,7 @@ mktemplate() {  # $1 = dir, $2 = unit count
     i=$((i + 1))
   done
   printf 'class Old {}\n' > "$T/javasource/m/Old.java"
+  [ "$APPTREE" = 1 ] && mkapptree "$T"
   printf 'CREATE MODULE "Bench";\n' > "$T/mdlsource/b.mdl"
   cp "$TOOLKIT/project-bin/_common.sh" "$TOOLKIT/project-bin/restore-mpr.sh" "$TOOLKIT/project-bin/snapshot-mpr.sh" "$T/bin/"
   cp "$SUBJECT" "$T/bin/exec.sh"
diff --git a/tests/wave2/test-exec-on-copy.sh b/tests/wave2/test-exec-on-copy.sh
index 63ebe478..275a1bdc 100755
--- a/tests/wave2/test-exec-on-copy.sh
+++ b/tests/wave2/test-exec-on-copy.sh
@@ -269,8 +269,29 @@ for LAYOUT in root app; do
   [ "$RC" -eq 1 ] && ok "refused (rc 1)" || bad "rc $RC"
   has "says FORCE_EXEC does not override" "$OUT" "FORCE_EXEC does not override"
   [ -e "$M/.mxtk-promote.997.committed" ] && ok "nothing touched" || bad "recovery ran while SP held the model"
+  has "#390: the refusal writes a BUILD-LOG row" "$(cat "$P/docs/BUILD-LOG.md" 2>/dev/null)" "🚫 blocked (Studio Pro holds the model)"
   kill "$SPP" 2>/dev/null; rm -f "$M/Fixture.mpr.lock"
 
+  for MODE in clone tar; do
+    echo "-- copy mode $MODE: build caches never copied, mtimes kept, promotion works"
+    P="$WORK/$LAYOUT-copy-$MODE"; mkproj "$P" "$SUB"; M="$P${SUB:+/$SUB}"
+    mkdir -p "$M/javascriptsource/m/node_modules/pkg" "$M/theme/web"; echo x > "$M/javascriptsource/m/node_modules/pkg/i.js"
+    echo y > "$M/javascriptsource/m/A.js"; echo s > "$M/theme/web/main.scss"
+    ( cd "$P" && git add -A && git -c user.email=t@t -c user.name=t commit -qm caches ) >/dev/null 2>&1
+    touch -t 200001010000 "$M/javasource/m/Old.java"   # a fresh mtime in the copy would be newer
+    STUB_MXB_ERR=1 MXTK_COPY_MODE=$MODE run "$P" --on-copy mdlsource/test.mdl >/dev/null
+    K="$(ls -d "$P/.mpr-snapshots/.on-copy/"*/ 2>/dev/null | head -1)"
+    [ -n "$K" ] && [ -f "$K/model/Fixture.mpr" ] && [ -f "$K/model/javascriptsource/m/A.js" ] && [ -f "$K/model/theme/web/main.scss" ] \
+      && ok "[$MODE] model and app dirs copied" || bad "[$MODE] copy incomplete: $(ls "$K/model" 2>/dev/null)"
+    [ -n "$K" ] && [ -z "$(find "$K/model" -name node_modules)" ] && ok "[$MODE] node_modules not copied" || bad "[$MODE] node_modules copied"
+    [ -n "$K" ] && [ ! "$K/model/javasource/m/Old.java" -nt "$M/javasource/m/Old.java" ] \
+      && ok "[$MODE] mtimes preserved" || bad "[$MODE] copied files got new mtimes"
+    OUT="$(STUB_SIDE=1 MXTK_COPY_MODE=$MODE run "$P" --on-copy mdlsource/test.mdl)"; RC=$?
+    [ "$RC" -eq 0 ] && grep -q 'changed by exec' "$M/Fixture.mpr" && [ -f "$M/javasource/m/New.java" ] \
+      && ok "[$MODE] clean run promotes" || bad "[$MODE] rc $RC: $(printf '%s' "$OUT" | tail -3)"
+    [ -f "$M/javascriptsource/m/node_modules/pkg/i.js" ] && ok "[$MODE] live node_modules untouched" || bad "[$MODE] live node_modules lost"
+  done
+
   echo "-- a side file written with an archive mtime is still promoted (by checksum)"
   P="$WORK/$LAYOUT-archmtime"; mkproj "$P" "$SUB"; M="$P${SUB:+/$SUB}"
   OUT="$(STUB_OLDMTIME=1 run "$P" --on-copy mdlsource/test.mdl)"; RC=$?
@@ -301,6 +322,13 @@ for LAYOUT in root app; do
   [ "$RC" -eq 1 ] && ok "refused (rc 1)" || bad "rc $RC"
   has "says FORCE_EXEC does not override" "$OUT" "FORCE_EXEC does not override"
   [ ! -f "$WORK/log/exec-targets" ] && ok "nothing executed" || bad "exec ran"
+  has "#390: the refusal writes a BUILD-LOG row" "$(cat "$P/docs/BUILD-LOG.md" 2>/dev/null)" "🚫 blocked (Studio Pro holds the model)"
+  echo "-- #390: with a DIRTY model and Studio Pro open, --on-copy reports Studio Pro (it is checked first)"
+  echo "uncommitted edit" >> "$M/mprcontents/ab/a.mxunit"
+  OUT="$(run "$P" --on-copy mdlsource/test.mdl)"; RC=$?
+  [ "$RC" -eq 1 ] && ok "refused (rc 1)" || bad "rc $RC"
+  has "the Studio Pro refusal, not the dirty-model one" "$OUT" "Studio Pro has Fixture open"
+  hasnt "the dirty-model guard was not reached" "$OUT" "Uncommitted model changes"
   kill "$SPP" 2>/dev/null
 done
 

From d426565a2b6c85f7154219ed86b9d86443696bf0 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 15 Oct 2026 05:06:35 +0000
Subject: [PATCH 6/7] fix(exec): detection prunes exactly MXTK_COPY_SKIP (#384
 confirmation review)

oc_side_manifest and oc_other_list pruned a hard-coded node_modules/.cache
while the copy skips the configurable MXTK_COPY_SKIP; both now build their
find prune list from that one variable. Skill note: .mendix-cache is not
copied, so a gate needing it may re-download into the copy.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
---
 project-bin/exec.sh            | 6 ++++--
 skills/iterative-build-loop.md | 2 +-
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/project-bin/exec.sh b/project-bin/exec.sh
index fefcd5d2..8fe99ce5 100755
--- a/project-bin/exec.sh
+++ b/project-bin/exec.sh
@@ -1104,8 +1104,10 @@ oc_fingerprint() {  # $1 = model dir. One cksum over the .mpr, its -wal, and eve
   ( cd "$1" && { cksum "$MPR_BASE"; [ -f "$MPR_BASE-wal" ] && cksum "$MPR_BASE-wal"
       if [ -d mprcontents ]; then find mprcontents -type f | LC_ALL=C sort | tr '\n' '\0' | xargs -0 cksum; fi; } ) 2>/dev/null | cksum
 }
+# Detection prunes exactly what the copy skips (_common.sh MXTK_COPY_SKIP), so the two never disagree.
+OC_PRUNE=(-name .mxtk-prune-none); for _s in $MXTK_COPY_SKIP; do OC_PRUNE+=(-o -name "$_s"); done
 oc_side_manifest() {  # $1 = model dir: "crc size path" per file under $OC_SIDE_DIRS, build caches pruned
-  ( cd "$1" && for _d in $OC_SIDE_DIRS; do [ -d "$_d" ] && find "$_d" \( -name node_modules -o -name .cache \) -prune \
+  ( cd "$1" && for _d in $OC_SIDE_DIRS; do [ -d "$_d" ] && find "$_d" \( "${OC_PRUNE[@]}" \) -prune \
       -o -type f -print; done | LC_ALL=C sort | tr '\n' '\0' | xargs -0 cksum | awk 'NF >= 3' ) 2>/dev/null
 }
 oc_side_sum() {  # $1 = file: "crc size", or "-" when it does not exist
@@ -1116,7 +1118,7 @@ oc_side_sum0() {  # $1 = rel path: its "crc size" in OC_SIDE0 (taken before the
 }
 oc_other_list() {  # $1 = copy [$2 = marker: only files newer]: sorted paths outside the model and $OC_SIDE_DIRS
   ( cd "$1" && find . \( -path ./mprcontents -o -path ./deployment -o -path ./.mxcli -o -path ./.git \
-      -o -name node_modules -o -name .cache \) -prune -o -type f ${2:+-newer "$2"} -print 2>/dev/null | sed 's|^\./||' | while IFS= read -r _r; do
+      -o "${OC_PRUNE[@]}" \) -prune -o -type f ${2:+-newer "$2"} -print 2>/dev/null | sed 's|^\./||' | while IFS= read -r _r; do
       case "$_r" in "$MPR_BASE"|"$MPR_BASE".*|"$MPR_BASE"-*) continue ;; esac
       _in=0; for _d in $OC_SIDE_DIRS; do case "$_r" in "$_d"/*) _in=1 ;; esac; done
       [ "$_in" = 1 ] || printf '%s\n' "$_r"
diff --git a/skills/iterative-build-loop.md b/skills/iterative-build-loop.md
index 8bce1b41..f73933af 100644
--- a/skills/iterative-build-loop.md
+++ b/skills/iterative-build-loop.md
@@ -293,7 +293,7 @@ is the part worth stating twice.
 | `last-mxbuild-errors.json` is cleared at the **start** of a run, not on success | An interrupted run must not leave a previous failure's file looking like its own report |
 | Studio Pro is never auto-killed; the reopen is offered, then done on a yes | See the SP Lifecycle Rule above |
 
-**Opt-in: `./bin/exec.sh --on-copy <script>` (or `EXEC_ON_COPY=1`).** By default the live model holds the script's unverified write for the length of the gate, and keeps it if exec.sh is killed. With `--on-copy`, `mxcli exec` and the mxbuild gate run on a scratch copy under the same lock. The live model is written only by a rename-based promotion after a verified pass with exit 0. Promotion is refused while Studio Pro holds the model (even under `FORCE_EXEC`) and when the live model changed since the copy was taken. On any refusal or failure the live model is byte-identical and the copy is kept under `.mpr-snapshots/.on-copy/`, with a resume hint. The copy is cloned where the filesystem allows and never includes build caches. On a single-tree checkout only the `.mpr` and the app directories are copied (`MXTK_APP_DIRS` in `_common.sh`), never `sources/`, `analysis/`, `docs/` or binaries. If a promotion is killed half-way, every exec and `test-scratch.sh` refuses until `./bin/exec.sh --recover-promote` has finished it or renamed it back; it is safe to run twice. After such a kill, run `--recover-promote` before editing anything. It is stub-tested only and not yet the default (toolkit #350).
+**Opt-in: `./bin/exec.sh --on-copy <script>` (or `EXEC_ON_COPY=1`).** By default the live model holds the script's unverified write for the length of the gate, and keeps it if exec.sh is killed. With `--on-copy`, `mxcli exec` and the mxbuild gate run on a scratch copy under the same lock. The live model is written only by a rename-based promotion after a verified pass with exit 0. Promotion is refused while Studio Pro holds the model (even under `FORCE_EXEC`) and when the live model changed since the copy was taken. On any refusal or failure the live model is byte-identical and the copy is kept under `.mpr-snapshots/.on-copy/`, with a resume hint. The copy is cloned where the filesystem allows and never includes build caches (`MXTK_COPY_SKIP`); without `.mendix-cache` a gate may re-download into the copy. On a single-tree checkout only the `.mpr` and the app directories are copied (`MXTK_APP_DIRS` in `_common.sh`), never `sources/`, `analysis/`, `docs/` or binaries. If a promotion is killed half-way, every exec and `test-scratch.sh` refuses until `./bin/exec.sh --recover-promote` has finished it or renamed it back; it is safe to run twice. After such a kill, run `--recover-promote` before editing anything. It is stub-tested only and not yet the default (toolkit #350).
 
 ### Standalone SP restart — `bin/restart-sp.sh`
 

From b65a16a94dc097ef8940bfe17f1142531f15bda1 Mon Sep 17 00:00:00 2001
From: MendixMau <mauritscgvisser@gmail.com>
Date: Fri, 16 Oct 2026 10:51:27 +0800
Subject: [PATCH 7/7] tests(exec-on-copy): macOS TMPDIR trailing slash and busy
 dev ports gave 8 false FAILs (#384)

WORK is normalised with cd + pwd (TMPDIR ends in a slash on macOS, so the exact-path
asserts compared T// against T/). The test-scratch M1 case now picks free loopback
ports instead of assuming 8081/8091 are free. 275/8 -> 283/0 on macOS 26, bash 3.2.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 tests/wave2/test-exec-on-copy.sh | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/tests/wave2/test-exec-on-copy.sh b/tests/wave2/test-exec-on-copy.sh
index 275a1bdc..a2f5f616 100755
--- a/tests/wave2/test-exec-on-copy.sh
+++ b/tests/wave2/test-exec-on-copy.sh
@@ -31,10 +31,17 @@ set -uo pipefail
 TOOLKIT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 SUBJECT="${1:-$TOOLKIT/project-bin/exec.sh}"
 case "$SUBJECT" in /*) ;; *) SUBJECT="$PWD/$SUBJECT" ;; esac
+# macOS TMPDIR ends in "/", so mktemp returns ".../T//execcopy.X"; exec.sh prints the resolved
+# ".../T/execcopy.X" and every exact-path assert below would fail. Normalise with cd + pwd.
 WORK="$(mktemp -d "${TMPDIR:-/tmp}/execcopy.XXXXXX")" || exit 2
+WORK="$(cd "$WORK" && pwd)" || exit 2
 BG=""
 cleanup() { for p in $BG; do kill -KILL "$p" 2>/dev/null; done; rm -rf "$WORK"; }
 trap cleanup EXIT
+# Two free loopback ports for test-scratch.sh (it refuses when :8081 or :8091 already answers,
+# e.g. a dev runtime on the same machine, which made the M1 case fail for environment reasons).
+free_port() { local p="$1"; while (exec 3<>"/dev/tcp/127.0.0.1/$p") 2>/dev/null; do p=$((p+1)); done; echo "$p"; }
+_P1="$(free_port 18081)"; _P2="$(free_port $((_P1+1)))"; export MXTK_TEST_PORTS="$_P1 $_P2"
 PASS=0; FAIL=0
 ok()  { PASS=$((PASS+1)); echo "  ok   — $1"; }
 bad() { FAIL=$((FAIL+1)); echo "  FAIL — $1"; }