diff --git a/.loopx/apply-adr/apply-feedback.sh b/.loopx/apply-adr/apply-feedback.sh
index c27088d..5910ec0 100755
--- a/.loopx/apply-adr/apply-feedback.sh
+++ b/.loopx/apply-adr/apply-feedback.sh
@@ -5,6 +5,7 @@ ROOT="$LOOPX_PROJECT_ROOT"
 SHARED_DIR="$ROOT/.loopx/shared"
 FEEDBACK_FILE="$SHARED_DIR/.feedback.tmp"
 CLAUDE_OUTPUT_FILE="$SHARED_DIR/.claude-output.tmp"
+SESSION_FILE="$SHARED_DIR/.session.tmp"
 
 if [[ ! -f "$FEEDBACK_FILE" ]]; then
   echo "Error: No feedback file found at $FEEDBACK_FILE" >&2
@@ -13,21 +14,19 @@ fi
 
 FEEDBACK=$(cat "$FEEDBACK_FILE")
 
-ADR_0002=$(cat "$ROOT/adr/0002-run-subcommand.md")
-SPEC=$(cat "$ROOT/SPEC.md")
+RESOLVED=$("$SHARED_DIR/resolve-adr.sh")
+IFS=$'\t' read -r ADR_NUM ADR_FILE <<< "$RESOLVED"
+ADR_REL="adr/$(basename "$ADR_FILE")"
 
-PROMPT="ADR-0002 has been accepted and I am now updating SPEC.md to incorporate its changes (per the ADR process in ADR-0001). I received the following feedback on the current state of SPEC.md. Apply this feedback by updating SPEC.md only. ADR-0002 is the authoritative reference for what should change — do not modify it. If there is any ambiguity about my intentions, ask me clarifying questions. Think critically about this feedback and push back if warranted. After you finish, commit and push.
-
-adr/0002-run-subcommand.md (accepted — read-only reference):
-$ADR_0002
-
-Current SPEC.md:
-$SPEC
+PROMPT="ADR-$ADR_NUM ($ADR_REL) has been accepted and I am now updating SPEC.md to incorporate its changes (per the ADR process in adr/0001-adr-process.md). I received the following feedback on the current state of SPEC.md. Apply this feedback by updating SPEC.md only. ADR-$ADR_NUM is the authoritative reference for what should change — do not modify it. SPEC.md should describe the current specification only — no migration notes, breaking changes, or references to prior versions. If there is any ambiguity about my intentions, ask me clarifying questions. When you ask questions, ask only one at a time and wait for my answer before asking the next — do not batch multiple questions together. I have not read the feedback, I only pasted it in, so phrase each question to stand on its own: include the relevant context or quote from the feedback so I can answer without having to go read it. Think critically about this feedback and push back if warranted. After you finish, commit and push.
 
 Feedback:
 $FEEDBACK"
 
-CLAUDE_OUTPUT=$(echo "$PROMPT" | claude --dangerously-skip-permissions -p 2>/dev/null)
+SESSION_ID=$(uuidgen | tr '[:upper:]' '[:lower:]')
+echo "$SESSION_ID" > "$SESSION_FILE"
+
+CLAUDE_OUTPUT=$(echo "$PROMPT" | claude --dangerously-skip-permissions --session-id "$SESSION_ID" -p 2>/dev/null)
 
 rm -f "$FEEDBACK_FILE"
 echo "$CLAUDE_OUTPUT" > "$CLAUDE_OUTPUT_FILE"
diff --git a/.loopx/apply-adr/index.sh b/.loopx/apply-adr/index.sh
index d16117f..75ba538 100755
--- a/.loopx/apply-adr/index.sh
+++ b/.loopx/apply-adr/index.sh
@@ -3,7 +3,6 @@ set -euo pipefail
 
 ROOT="$LOOPX_PROJECT_ROOT"
 ADR_0001="$ROOT/adr/0001-adr-process.md"
-ADR_0002="$ROOT/adr/0002-run-subcommand.md"
 SPEC="$ROOT/SPEC.md"
 SHARED_DIR="$ROOT/.loopx/shared"
 PROMPT_FILE="$SHARED_DIR/.prompt.tmp"
@@ -19,23 +18,22 @@ if [[ ! -f "$ADR_0001" ]]; then
   exit 1
 fi
 
-if [[ ! -f "$ADR_0002" ]]; then
-  echo "Error: adr/0002-run-subcommand.md not found" >&2
-  exit 1
-fi
-
 if [[ ! -f "$SPEC" ]]; then
   echo "Error: SPEC.md not found" >&2
   exit 1
 fi
 
+RESOLVED=$("$SHARED_DIR/resolve-adr.sh")
+IFS=$'\t' read -r ADR_NUM ADR_FILE <<< "$RESOLVED"
+ADR_REL="adr/$(basename "$ADR_FILE")"
+
 echo "$LOOPX_WORKFLOW" > "$CALLER_FILE"
 
 cat <<PROMPT > "$PROMPT_FILE"
-ADR 0002 has been accepted. The next step in the process is to update SPEC.md to incorporate the changes described in ADR 0002. Review the current SPEC.md against ADR 0002 and let me know if the SPEC updates look correct and complete, or if anything else in the SPEC needs to be changed.
+ADR $ADR_NUM has been accepted. The next step in the process is to update SPEC.md to incorporate the changes described in ADR $ADR_NUM. Review the current SPEC.md against ADR $ADR_NUM and let me know if the SPEC updates look correct and complete, or if anything else in the SPEC needs to be changed.
 
-adr/0002-run-subcommand.md (accepted — do not modify):
-$(cat "$ADR_0002")
+$ADR_REL (accepted — do not modify):
+$(cat "$ADR_FILE")
 
 SPEC.md (target of updates):
 $(cat "$SPEC")
diff --git a/.loopx/ralph/check-ready.sh b/.loopx/ralph/check-ready.sh
index 7d40193..9845fc9 100755
--- a/.loopx/ralph/check-ready.sh
+++ b/.loopx/ralph/check-ready.sh
@@ -19,10 +19,11 @@ echo "=== Readiness verdict: ${VERDICT} ===" >&2
 
 if echo "$VERDICT" | grep -qw "READY"; then
   ITER=$(cat "$ITER_FILE" 2>/dev/null || echo "?")
+  JOB="$(basename "$ROOT") / ralph"
 
   curl -s -X POST "${TELEGRAM_API}/sendMessage" \
     -d chat_id="$TELEGRAM_CHAT_ID" \
-    --data-urlencode "text=Ralph loop: production ready after iteration ${ITER}. Halting." > /dev/null
+    --data-urlencode "text=[${JOB}] production ready after iteration ${ITER}. Halting." > /dev/null
 
   rm -f "$ITER_FILE"
   echo "=== Production ready — halting loop ===" >&2
diff --git a/.loopx/ralph/index.sh b/.loopx/ralph/index.sh
index 80398a5..d253e32 100755
--- a/.loopx/ralph/index.sh
+++ b/.loopx/ralph/index.sh
@@ -22,9 +22,11 @@ else
 fi
 echo "$ITER" > "$ITER_FILE"
 
+JOB="$(basename "$ROOT") / ralph"
+
 curl -s -X POST "${TELEGRAM_API}/sendMessage" \
   -d chat_id="$TELEGRAM_CHAT_ID" \
-  --data-urlencode "text=Ralph loop: starting iteration ${ITER}" > /dev/null
+  --data-urlencode "text=[${JOB}] starting iteration ${ITER}" > /dev/null
 
 echo "=== Ralph iteration ${ITER} ===" >&2
 
diff --git a/.loopx/review-adr/apply-feedback.sh b/.loopx/review-adr/apply-feedback.sh
index f13be69..ae292ee 100755
--- a/.loopx/review-adr/apply-feedback.sh
+++ b/.loopx/review-adr/apply-feedback.sh
@@ -5,6 +5,7 @@ ROOT="$LOOPX_PROJECT_ROOT"
 SHARED_DIR="$ROOT/.loopx/shared"
 FEEDBACK_FILE="$SHARED_DIR/.feedback.tmp"
 CLAUDE_OUTPUT_FILE="$SHARED_DIR/.claude-output.tmp"
+SESSION_FILE="$SHARED_DIR/.session.tmp"
 
 if [[ ! -f "$FEEDBACK_FILE" ]]; then
   echo "Error: No feedback file found at $FEEDBACK_FILE" >&2
@@ -13,12 +14,19 @@ fi
 
 FEEDBACK=$(cat "$FEEDBACK_FILE")
 
-PROMPT="I received the following feedback about ADR-0004 (run-scoped tmpdir and script args proposal) and its relationship to SPEC.md as defined by the the process laid out in ADR-0001. Incorporate this feedback to improve ADR-0004. If there is any ambiguity about my intentions, ask me clarifying questions. Think critically about this feedback and push back if warranted. Do not update any file other than ADR-0004 and do not mark it as accepted. After you finish, commit and push.
+RESOLVED=$("$SHARED_DIR/resolve-adr.sh")
+IFS=$'\t' read -r ADR_NUM ADR_FILE <<< "$RESOLVED"
+ADR_REL="adr/$(basename "$ADR_FILE")"
+
+PROMPT="I received the following feedback about ADR-$ADR_NUM ($ADR_REL) and its relationship to SPEC.md as defined by the process laid out in ADR-0001. Incorporate this feedback to improve ADR-$ADR_NUM. Use your judgement on the best implementation details to achieve the product goals; if there is any ambiguity about my intentions, ask me clarifying questions from a product perspective rather than an implementation perspective. When you ask questions, ask only one at a time and wait for my answer before asking the next — do not batch multiple questions together. I have not read the feedback, I only pasted it in, so phrase each question to stand on its own: include the relevant context or quote from the feedback so I can answer without having to go read it. Think critically about this feedback and push back if warranted. Don't include migration details for existing users. Only include what is necessary to thoroughly update SPEC.md — keep additional information (such as testing considerations) to a minimum, because the primary purpose of this ADR is to be used to update SPEC.md. Do not update any file other than ADR-$ADR_NUM and do not mark it as accepted. After you finish, commit and push.
 
 Feedback:
 $FEEDBACK"
 
-CLAUDE_OUTPUT=$(echo "$PROMPT" | claude --dangerously-skip-permissions -p 2>/dev/null)
+SESSION_ID=$(uuidgen | tr '[:upper:]' '[:lower:]')
+echo "$SESSION_ID" > "$SESSION_FILE"
+
+CLAUDE_OUTPUT=$(echo "$PROMPT" | claude --dangerously-skip-permissions --session-id "$SESSION_ID" -p 2>/dev/null)
 
 rm -f "$FEEDBACK_FILE"
 echo "$CLAUDE_OUTPUT" > "$CLAUDE_OUTPUT_FILE"
diff --git a/.loopx/review-adr/index.sh b/.loopx/review-adr/index.sh
index 4f70e93..09473d4 100755
--- a/.loopx/review-adr/index.sh
+++ b/.loopx/review-adr/index.sh
@@ -3,7 +3,6 @@ set -euo pipefail
 
 ROOT="$LOOPX_PROJECT_ROOT"
 ADR_0001="$ROOT/adr/0001-adr-process.md"
-ADR_0004="$ROOT/adr/0004-tmpdir-and-args.md"
 SPEC="$ROOT/SPEC.md"
 SHARED_DIR="$ROOT/.loopx/shared"
 PROMPT_FILE="$SHARED_DIR/.prompt.tmp"
@@ -19,26 +18,27 @@ if [[ ! -f "$ADR_0001" ]]; then
   exit 1
 fi
 
-if [[ ! -f "$ADR_0004" ]]; then
-  echo "Error: adr/0004-tmpdir-and-args.md not found" >&2
-  exit 1
-fi
-
 if [[ ! -f "$SPEC" ]]; then
   echo "Error: SPEC.md not found" >&2
   exit 1
 fi
 
+RESOLVED=$("$SHARED_DIR/resolve-adr.sh")
+IFS=$'\t' read -r ADR_NUM ADR_FILE <<< "$RESOLVED"
+ADR_REL="adr/$(basename "$ADR_FILE")"
+
 echo "$LOOPX_WORKFLOW" > "$CALLER_FILE"
 
 cat <<PROMPT > "$PROMPT_FILE"
-Review ADR 0001, ADR 0004, and SPEC.md holistically and let me know if I can mark ADR 0004 as accepted or if I need to improve it further. Ask me clarifying questions if you have any doubts about my intentions for ADR 0004.
-
 adr/0001-adr-process.md:
 $(cat "$ADR_0001")
 
-adr/0004-tmpdir-and-args.md:
-$(cat "$ADR_0004")
+---
+
+Review ADR $ADR_NUM and SPEC.md against the process described in adr/0001-adr-process.md above. Let me know if I can mark ADR $ADR_NUM as accepted or if I need to improve it further. Ask me clarifying questions if you have any doubts about my intentions for ADR $ADR_NUM.
+
+$ADR_REL:
+$(cat "$ADR_FILE")
 
 SPEC.md:
 $(cat "$SPEC")
diff --git a/.loopx/review-spec/apply-feedback.sh b/.loopx/review-spec/apply-feedback.sh
new file mode 100755
index 0000000..02f3392
--- /dev/null
+++ b/.loopx/review-spec/apply-feedback.sh
@@ -0,0 +1,32 @@
+#!/bin/bash
+set -euo pipefail
+
+ROOT="$LOOPX_PROJECT_ROOT"
+SHARED_DIR="$ROOT/.loopx/shared"
+FEEDBACK_FILE="$SHARED_DIR/.feedback.tmp"
+CLAUDE_OUTPUT_FILE="$SHARED_DIR/.claude-output.tmp"
+SESSION_FILE="$SHARED_DIR/.session.tmp"
+
+if [[ ! -f "$FEEDBACK_FILE" ]]; then
+  echo "Error: No feedback file found at $FEEDBACK_FILE" >&2
+  exit 1
+fi
+
+FEEDBACK=$(cat "$FEEDBACK_FILE")
+
+PROMPT="I got this feedback from a review of @SPEC.md please incorporate this feedback. Use your judgement to make implementation decisions as long as they are aligned with my product vision. If there is any ambiguity about my intentions, ask me clarifying questions from a product perspective rather than an implementation perspective. When you ask questions, ask only one at a time and wait for my answer before asking the next — do not batch multiple questions together. I have not read the feedback, I only pasted it in, so phrase each question to stand on its own: include the relevant context or quote from the feedback so I can answer without having to go read it. Think critically and push back if needed. Only modify SPEC.md and after you are done, commit and push:
+
+$FEEDBACK"
+
+SESSION_ID=$(uuidgen | tr '[:upper:]' '[:lower:]')
+echo "$SESSION_ID" > "$SESSION_FILE"
+
+CLAUDE_OUTPUT=$(echo "$PROMPT" | claude --dangerously-skip-permissions --session-id "$SESSION_ID" -p 2>/dev/null)
+
+rm -f "$FEEDBACK_FILE"
+echo "$CLAUDE_OUTPUT" > "$CLAUDE_OUTPUT_FILE"
+
+echo "" >&2
+echo "=== Claude finished applying feedback ===" >&2
+
+$LOOPX_BIN output --goto "shared:check-question"
diff --git a/.loopx/review-spec/index.sh b/.loopx/review-spec/index.sh
new file mode 100755
index 0000000..e55a439
--- /dev/null
+++ b/.loopx/review-spec/index.sh
@@ -0,0 +1,29 @@
+#!/bin/bash
+set -euo pipefail
+
+ROOT="$LOOPX_PROJECT_ROOT"
+SPEC="$ROOT/SPEC.md"
+SHARED_DIR="$ROOT/.loopx/shared"
+PROMPT_FILE="$SHARED_DIR/.prompt.tmp"
+CALLER_FILE="$SHARED_DIR/.caller.tmp"
+
+if [[ ! -d "$SHARED_DIR" ]]; then
+  echo "Error: shared workflow not found at $SHARED_DIR — install it with: loopx install -w shared modularcloud/sdg-workflows" >&2
+  exit 1
+fi
+
+if [[ ! -f "$SPEC" ]]; then
+  echo "Error: SPEC.md not found at $SPEC — review-spec requires SPEC.md to exist at the project root" >&2
+  exit 1
+fi
+
+echo "$LOOPX_WORKFLOW" > "$CALLER_FILE"
+
+cat <<PROMPT > "$PROMPT_FILE"
+Review my specification and let me know if this is implementation-ready or if you have feedback. To refine your feedback, feel free to ask questions.
+
+SPEC.md:
+$(cat "$SPEC")
+PROMPT
+
+$LOOPX_BIN output --goto "shared:dispatch"
diff --git a/.loopx/review-test-spec/apply-feedback.sh b/.loopx/review-test-spec/apply-feedback.sh
new file mode 100755
index 0000000..060334b
--- /dev/null
+++ b/.loopx/review-test-spec/apply-feedback.sh
@@ -0,0 +1,38 @@
+#!/bin/bash
+set -euo pipefail
+
+ROOT="$LOOPX_PROJECT_ROOT"
+SHARED_DIR="$ROOT/.loopx/shared"
+FEEDBACK_FILE="$SHARED_DIR/.feedback.tmp"
+CLAUDE_OUTPUT_FILE="$SHARED_DIR/.claude-output.tmp"
+SESSION_FILE="$SHARED_DIR/.session.tmp"
+
+if [[ ! -f "$FEEDBACK_FILE" ]]; then
+  echo "Error: No feedback file found at $FEEDBACK_FILE" >&2
+  exit 1
+fi
+
+RESOLVED=$("$SHARED_DIR/resolve-adr.sh")
+IFS=$'\t' read -r ADR_NUM ADR_FILE <<< "$RESOLVED"
+
+FEEDBACK=$(cat "$FEEDBACK_FILE")
+
+PROMPT="I received the following feedback on TEST-SPEC.md with respect to SPEC.md. Apply this feedback by updating TEST-SPEC.md. SPEC.md is the authoritative source for what TEST-SPEC.md should cover.
+
+This review and any feedback you apply is scoped to ADR-$ADR_NUM. You are allowed to modify SPEC.md only when the feedback proposes a specific SPEC change that resolves a SPEC-PROBLEMS.md entry scoped to ADR-$ADR_NUM, and you MUST verify any proposed SPEC.md edits with me before applying them — show me the exact diff and wait for explicit approval. Do **not** apply SPEC.md changes that are unrelated to ADR-$ADR_NUM, even if the feedback proposes them — push back and explain that those changes are out of scope for this cycle. If you find a problem in the spec (an ambiguity, gap, or under-specified clause that prevents TEST-SPEC.md from covering the behavior cleanly) and that problem is scoped to ADR-$ADR_NUM, add it to SPEC-PROBLEMS.md so we can work to resolve it in a follow-up cycle; do not record problems unrelated to ADR-$ADR_NUM. If there are no remaining problems in the spec scoped to ADR-$ADR_NUM, delete SPEC-PROBLEMS.md. If there is any ambiguity about my intentions, ask me clarifying questions. When you ask questions, ask only one at a time and wait for my answer before asking the next — do not batch multiple questions together. I have not read the feedback, I only pasted it in, so phrase each question to stand on its own: include the relevant context or quote from the feedback so I can answer without having to go read it. Think critically about this feedback and push back if warranted. After you finish, commit and push.
+
+Feedback:
+$FEEDBACK"
+
+SESSION_ID=$(uuidgen | tr '[:upper:]' '[:lower:]')
+echo "$SESSION_ID" > "$SESSION_FILE"
+
+CLAUDE_OUTPUT=$(echo "$PROMPT" | claude --dangerously-skip-permissions --session-id "$SESSION_ID" -p 2>/dev/null)
+
+rm -f "$FEEDBACK_FILE"
+echo "$CLAUDE_OUTPUT" > "$CLAUDE_OUTPUT_FILE"
+
+echo "" >&2
+echo "=== Claude finished applying feedback ===" >&2
+
+$LOOPX_BIN output --goto "shared:check-question"
diff --git a/.loopx/review-test-spec/index.sh b/.loopx/review-test-spec/index.sh
new file mode 100755
index 0000000..7c578bc
--- /dev/null
+++ b/.loopx/review-test-spec/index.sh
@@ -0,0 +1,54 @@
+#!/bin/bash
+set -euo pipefail
+
+ROOT="$LOOPX_PROJECT_ROOT"
+SPEC="$ROOT/SPEC.md"
+TEST_SPEC="$ROOT/TEST-SPEC.md"
+SPEC_PROBLEMS="$ROOT/SPEC-PROBLEMS.md"
+SHARED_DIR="$ROOT/.loopx/shared"
+PROMPT_FILE="$SHARED_DIR/.prompt.tmp"
+CALLER_FILE="$SHARED_DIR/.caller.tmp"
+
+if [[ ! -d "$SHARED_DIR" ]]; then
+  echo "Error: shared workflow not found at $SHARED_DIR — install it with: loopx install -w shared modularcloud/sdg-workflows" >&2
+  exit 1
+fi
+
+if [[ ! -f "$SPEC" ]]; then
+  echo "Error: SPEC.md not found at $SPEC — review-test-spec requires SPEC.md to exist at the project root" >&2
+  exit 1
+fi
+
+if [[ ! -f "$TEST_SPEC" ]]; then
+  echo "Error: TEST-SPEC.md not found at $TEST_SPEC — review-test-spec requires TEST-SPEC.md to exist at the project root" >&2
+  exit 1
+fi
+
+RESOLVED=$("$SHARED_DIR/resolve-adr.sh")
+IFS=$'\t' read -r ADR_NUM ADR_FILE <<< "$RESOLVED"
+ADR_REL="adr/$(basename "$ADR_FILE")"
+
+echo "$LOOPX_WORKFLOW" > "$CALLER_FILE"
+
+if [[ -f "$SPEC_PROBLEMS" ]]; then
+  SPEC_PROBLEMS_BLOCK="$(printf 'SPEC-PROBLEMS.md (open SPEC ambiguities scoped to ADR-%s — please also work to resolve any problems listed here):\n%s\n\n' "$ADR_NUM" "$(cat "$SPEC_PROBLEMS")")"
+else
+  SPEC_PROBLEMS_BLOCK="SPEC-PROBLEMS.md is absent — there are no currently tracked open SPEC ambiguities scoped to ADR-${ADR_NUM}."$'\n\n'
+fi
+
+cat <<PROMPT > "$PROMPT_FILE"
+Review TEST-SPEC.md against SPEC.md and let me know whether TEST-SPEC.md covers the behavior described in SPEC.md correctly and completely, or what needs to be added, changed, or removed.
+
+This review is scoped to ADR-$ADR_NUM. SPEC.md changes are permitted **only** when they directly resolve a SPEC-PROBLEMS.md entry that is itself scoped to ADR-$ADR_NUM. Do **not** propose SPEC.md edits unrelated to ADR-$ADR_NUM, even if you notice gaps, ambiguities, or improvements in other sections of SPEC.md — those are out of scope for this cycle. Also work to resolve any problems in SPEC-PROBLEMS.md (if present) — call out which entries appear addressable in this cycle and which still require a SPEC change. If SPEC-PROBLEMS.md exists, you may propose specific SPEC.md edits that would resolve the listed ambiguities, but only when those edits are scoped to ADR-$ADR_NUM. If you find a SPEC ambiguity, gap, or under-specified clause that prevents TEST-SPEC.md from covering ADR-$ADR_NUM behavior cleanly, recommend adding it to SPEC-PROBLEMS.md; do not record problems unrelated to ADR-$ADR_NUM.
+
+$ADR_REL (scope of this review — SPEC and SPEC-PROBLEMS changes must be related to this ADR):
+$(cat "$ADR_FILE")
+
+SPEC.md (authoritative reference; SPEC.md edits are permitted only to resolve SPEC-PROBLEMS.md entries scoped to ADR-$ADR_NUM):
+$(cat "$SPEC")
+
+${SPEC_PROBLEMS_BLOCK}TEST-SPEC.md (target of updates):
+$(cat "$TEST_SPEC")
+PROMPT
+
+$LOOPX_BIN output --goto "shared:dispatch"
diff --git a/.loopx/shared/apply-answer.sh b/.loopx/shared/apply-answer.sh
index d406614..837b17c 100755
--- a/.loopx/shared/apply-answer.sh
+++ b/.loopx/shared/apply-answer.sh
@@ -4,16 +4,33 @@ set -euo pipefail
 ROOT="$LOOPX_PROJECT_ROOT"
 CLAUDE_OUTPUT_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.claude-output.tmp"
 ANSWER_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.answer.tmp"
+SESSION_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.session.tmp"
+CALLER_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.caller.tmp"
 
 if [[ ! -f "$ANSWER_FILE" ]]; then
   echo "Error: No answer file found at $ANSWER_FILE" >&2
   exit 1
 fi
 
+if [[ ! -f "$SESSION_FILE" ]]; then
+  echo "Error: No session file found at $SESSION_FILE — apply-feedback must run first" >&2
+  exit 1
+fi
+
+if [[ ! -f "$CALLER_FILE" ]]; then
+  echo "Error: No caller file found at $CALLER_FILE" >&2
+  exit 1
+fi
+
 ANSWER=$(cat "$ANSWER_FILE")
+SESSION_ID=$(cat "$SESSION_FILE")
+CALLER=$(cat "$CALLER_FILE")
+CALLER_DIR="$ROOT/.loopx/$CALLER"
 
-# Continue the existing conversation started by apply-feedback
-CLAUDE_OUTPUT=$(echo "$ANSWER" | claude --dangerously-skip-permissions -c -p 2>/dev/null)
+# Resume the session started by the caller's apply-feedback. Claude Code
+# stores session files per-cwd, so we must cd into the caller's workflow
+# directory before --resume can locate the session.
+CLAUDE_OUTPUT=$(cd "$CALLER_DIR" && echo "$ANSWER" | claude --dangerously-skip-permissions --resume "$SESSION_ID" -p 2>/dev/null)
 
 echo "$CLAUDE_OUTPUT" > "$CLAUDE_OUTPUT_FILE"
 rm -f "$ANSWER_FILE"
diff --git a/.loopx/shared/check-feedback-done.sh b/.loopx/shared/check-feedback-done.sh
index 8d0f05a..f70e623 100755
--- a/.loopx/shared/check-feedback-done.sh
+++ b/.loopx/shared/check-feedback-done.sh
@@ -1,6 +1,10 @@
 #!/bin/bash
 set -euo pipefail
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=./telegram-lib.sh
+source "$SCRIPT_DIR/telegram-lib.sh"
+
 ROOT="$LOOPX_PROJECT_ROOT"
 FEEDBACK_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.feedback.tmp"
 SCHEMA="$ROOT/.loopx/$LOOPX_WORKFLOW/check-feedback-done.schema.json"
@@ -25,7 +29,7 @@ CALLER=$(cat "$CALLER_FILE")
 
 FEEDBACK=$(cat "$FEEDBACK_FILE")
 
-VERDICT=$(codex exec --output-schema "$SCHEMA" "I received this feedback for my specs. Is it requiring that I continue making improvements before calling this stage of feedback done? Ignore optional feedback. Return done=true only if the response says we can be done explicitly and/or there are no further non-optional pieces of feedback. Note: if it says 'make this important change and then you are done', that does NOT count as done — return done=false.
+VERDICT=$(codex exec --sandbox read-only --output-schema "$SCHEMA" "I received this feedback for my specs. Is it requiring that I continue making improvements before calling this stage of feedback done? Ignore optional feedback. Return done=true only if the response says we can be done explicitly and/or there are no further non-optional pieces of feedback. Note: if it says 'make this important change and then you are done', that does NOT count as done — return done=false.
 
 Feedback:
 $FEEDBACK" 2>/dev/null)
@@ -34,7 +38,13 @@ DONE=$(echo "$VERDICT" | jq -r '.done')
 
 if [[ "$DONE" == "true" ]]; then
   echo "=== Feedback indicates no further non-optional improvements — halting ===" >&2
-  rm -f "$FEEDBACK_FILE" "$CALLER_FILE"
+
+  ALERT_LABEL=$(tg_alert_label)
+  curl -s -X POST "${TELEGRAM_API}/sendMessage" \
+    -d chat_id="$TELEGRAM_CHAT_ID" \
+    --data-urlencode "text=[${ALERT_LABEL}] Feedback indicates no further non-optional improvements. Halting." > /dev/null
+
+  rm -f "$FEEDBACK_FILE" "$CALLER_FILE" "$ROOT/.loopx/$LOOPX_WORKFLOW/.session.tmp"
   $LOOPX_BIN output --result "Feedback indicates no further non-optional improvements. Halting." --stop
 else
   echo "=== Feedback requires further improvements — applying ===" >&2
diff --git a/.loopx/shared/check-question.schema.json b/.loopx/shared/check-question.schema.json
index fe39a58..ac9f0ee 100644
--- a/.loopx/shared/check-question.schema.json
+++ b/.loopx/shared/check-question.schema.json
@@ -2,7 +2,7 @@
   "type": "object",
   "properties": {
     "has_question": {
-      "description": "true if the text contains a question or request for clarification directed at the user, false otherwise",
+      "description": "true only if the text contains an actual pending question that blocks completion of the work (the agent needs an answer before proceeding); false for sign-offs that report work as complete and invite post-hoc corrections",
       "type": "boolean"
     }
   },
diff --git a/.loopx/shared/check-question.sh b/.loopx/shared/check-question.sh
index 7fa51e0..53c1c2f 100755
--- a/.loopx/shared/check-question.sh
+++ b/.loopx/shared/check-question.sh
@@ -1,105 +1,180 @@
 #!/bin/bash
 set -euo pipefail
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=./telegram-lib.sh
+source "$SCRIPT_DIR/telegram-lib.sh"
+
 ROOT="$LOOPX_PROJECT_ROOT"
 CLAUDE_OUTPUT_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.claude-output.tmp"
 ANSWER_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.answer.tmp"
 
-: "${TELEGRAM_BOT_TOKEN:?TELEGRAM_BOT_TOKEN env var is required}"
-: "${TELEGRAM_CHAT_ID:?TELEGRAM_CHAT_ID env var is required}"
-
-TELEGRAM_API="https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}"
-
 if [[ ! -f "$CLAUDE_OUTPUT_FILE" ]]; then
   echo "Error: No Claude output file found at $CLAUDE_OUTPUT_FILE" >&2
   exit 1
 fi
 
 CLAUDE_OUTPUT=$(cat "$CLAUDE_OUTPUT_FILE")
+CLAUDE_OUTPUT_HTML=$(printf '%s' "$CLAUDE_OUTPUT" | node "$SCRIPT_DIR/md-to-tg-html.mjs")
 
 # Use Codex with output schema to deterministically classify the output
 SCHEMA="$ROOT/.loopx/$LOOPX_WORKFLOW/check-question.schema.json"
-VERDICT=$(codex exec --output-schema "$SCHEMA" "Does the following text contain a question or request for clarification directed at the user?
+VERDICT=$(codex exec --sandbox read-only --output-schema "$SCHEMA" "Does the following text contain an actual question that blocks completion of the work — i.e., the agent cannot continue or finish until the user answers?
+
+Do NOT count these as blocking questions:
+- Sign-offs that report work as complete and invite post-hoc corrections (e.g., \"I finished X, let me know if anything is wrong\" or \"Tell me if I got something wrong\"). Correcting wrong assumptions is not a priority — treat these as has_question=false.
+- General invitations for follow-up feedback after the work is already done.
+
+Return has_question=true only when the text is paused on a pending question the agent needs an answer to before proceeding. When in doubt, prefer has_question=false.
 
 $CLAUDE_OUTPUT" 2>/dev/null)
 
 HAS_QUESTION=$(echo "$VERDICT" | jq -r '.has_question')
 
+TOPIC_NAME=$(tg_topic_name)
+ALERT_LABEL=$(tg_alert_label)
+
 if [[ "$HAS_QUESTION" == "true" ]]; then
-  echo "=== Claude has a question — sending to Telegram ===" >&2
-
-  # Send as document if too long for a message, otherwise as text
-  if [[ ${#CLAUDE_OUTPUT} -gt 4000 ]]; then
-    QUESTION_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.question.tmp"
-    echo "$CLAUDE_OUTPUT" > "$QUESTION_FILE"
-    curl -s -X POST "${TELEGRAM_API}/sendDocument" \
-      -F chat_id="$TELEGRAM_CHAT_ID" \
-      -F document=@"$QUESTION_FILE;filename=question.md" \
-      -F caption="Claude has a question — reply with your answer" > /dev/null
-    rm -f "$QUESTION_FILE"
-  else
-    curl -s -X POST "${TELEGRAM_API}/sendMessage" \
-      -d chat_id="$TELEGRAM_CHAT_ID" \
-      --data-urlencode "text=${CLAUDE_OUTPUT}" > /dev/null
+  echo "=== Claude has a question — sending to Telegram topic '$TOPIC_NAME' ===" >&2
+
+  THREAD_ID=$(tg_resolve_topic_id "$TOPIC_NAME")
+
+  # Watermark BEFORE sending so a near-instant reply isn't filtered out. Use
+  # negative offset to peek the tail without advancing the global confirmation
+  # pointer — confirming would delete updates queued for parallel runs.
+  SENTINEL=$(curl -s "${TELEGRAM_API}/getUpdates?offset=-1&limit=1" | jq -r '.result[-1].update_id // 0')
+
+  # Telegram caps sendMessage text at 4096 chars; chunk at 4000 to leave headroom
+  # for UTF-16 surrogate pairs (${#var} counts code points, not code units).
+  send_question() {
+    local thread="$1"
+    local max=4000
+    local remaining="$CLAUDE_OUTPUT_HTML"
+    local response=""
+    local first=1
+    while (( ${#remaining} > 0 )); do
+      local chunk
+      if (( ${#remaining} <= max )); then
+        chunk="$remaining"
+        remaining=""
+      else
+        local window="${remaining:0:$max}"
+        local trimmed="${window%$'\n'*}"
+        if [[ "$trimmed" != "$window" && ${#trimmed} -gt $((max / 2)) ]]; then
+          chunk="${trimmed}"$'\n'
+        else
+          chunk="$window"
+        fi
+        remaining="${remaining:${#chunk}}"
+      fi
+      response=$(curl -s -X POST "${TELEGRAM_API}/sendMessage" \
+        -d chat_id="$TELEGRAM_CHAT_ID" \
+        -d message_thread_id="$thread" \
+        -d parse_mode=HTML \
+        --data-urlencode "text=${chunk}")
+      # Chunking can split inside an HTML tag; on a parse error fall back to
+      # plain text for that chunk so the message still lands.
+      if [[ "$(echo "$response" | jq -r '.ok')" != "true" ]]; then
+        local desc
+        desc=$(echo "$response" | jq -r '.description // ""')
+        if [[ "$desc" == *"can't parse entities"* || "$desc" == *"Can't parse entities"* ]]; then
+          response=$(curl -s -X POST "${TELEGRAM_API}/sendMessage" \
+            -d chat_id="$TELEGRAM_CHAT_ID" \
+            -d message_thread_id="$thread" \
+            --data-urlencode "text=${chunk}")
+        fi
+      fi
+      if [[ "$(echo "$response" | jq -r '.ok')" != "true" ]]; then
+        # First-chunk failure bubbles up so the caller can retry on stale thread.
+        # Later-chunk failures can't be undone, so warn and keep going.
+        if (( first )); then
+          echo "$response"
+          return
+        fi
+        echo "Warning: failed to send follow-up chunk: $response" >&2
+      fi
+      first=0
+    done
+    echo "$response"
+  }
+
+  SEND_RESPONSE=$(send_question "$THREAD_ID")
+  if [[ "$(echo "$SEND_RESPONSE" | jq -r '.ok')" != "true" ]]; then
+    DESC=$(echo "$SEND_RESPONSE" | jq -r '.description // ""')
+    if tg_is_stale_thread_error "$DESC"; then
+      echo "Warning: cached topic $THREAD_ID no longer usable — recreating..." >&2
+      tg_forget_topic "$TOPIC_NAME"
+      THREAD_ID=$(tg_resolve_topic_id "$TOPIC_NAME")
+      SEND_RESPONSE=$(send_question "$THREAD_ID")
+    fi
   fi
-
-  echo "Waiting for answer..." >&2
-
-  # Flush old updates to get current offset
-  FLUSH_RESPONSE=$(curl -s "${TELEGRAM_API}/getUpdates?offset=-1")
-  LAST_UPDATE_ID=$(echo "$FLUSH_RESPONSE" | jq -r '.result[-1].update_id // empty')
-  if [[ -n "$LAST_UPDATE_ID" ]]; then
-    OFFSET=$((LAST_UPDATE_ID + 1))
-  else
-    OFFSET=0
+  if [[ "$(echo "$SEND_RESPONSE" | jq -r '.ok')" != "true" ]]; then
+    echo "Error: Failed to send question to Telegram: $SEND_RESPONSE" >&2
+    exit 1
   fi
 
-  # Long-poll for a reply, collecting split messages over a 10s window
+  echo "Waiting for answer in topic '$TOPIC_NAME' (thread $THREAD_ID)..." >&2
+
   COLLECTED=""
   DEADLINE=""
 
   while true; do
-    if [[ -n "$DEADLINE" ]]; then
-      NOW=$(date +%s)
-      if [[ $NOW -ge $DEADLINE ]]; then
-        break
-      fi
-      POLL_TIMEOUT=2
-    else
-      POLL_TIMEOUT=30
+    # Negative offset + sentinel: read the tail without advancing the global
+    # confirmation pointer, and filter per-run by thread_id so parallel review
+    # cycles don't steal each other's answers.
+    UPDATES=$(curl -s "${TELEGRAM_API}/getUpdates?offset=-100&limit=100")
+    if [[ "$(echo "$UPDATES" | jq -r '.ok // false')" != "true" ]]; then
+      sleep 2
+      continue
     fi
 
-    UPDATES=$(curl -s "${TELEGRAM_API}/getUpdates?offset=${OFFSET}&timeout=${POLL_TIMEOUT}")
-
-    MSG_COUNT=$(echo "$UPDATES" | jq --arg cid "$TELEGRAM_CHAT_ID" '
-      [.result[] | select(.message.chat.id == ($cid | tonumber) and .message.text != null)] | length
+    BATCH=$(echo "$UPDATES" | jq -r \
+      --arg cid "$TELEGRAM_CHAT_ID" \
+      --argjson thread "$THREAD_ID" \
+      --argjson sentinel "$SENTINEL" '
+      [.result[]
+        | select(.message.chat.id == ($cid|tonumber)
+                 and .message.text != null
+                 and (.message.message_thread_id // 0) == $thread
+                 and .update_id > $sentinel)]
+      | map(.message.text) | join("\n")
+    ')
+    MAX_ID=$(echo "$UPDATES" | jq -r \
+      --arg cid "$TELEGRAM_CHAT_ID" \
+      --argjson thread "$THREAD_ID" \
+      --argjson sentinel "$SENTINEL" '
+      [.result[]
+        | select(.message.chat.id == ($cid|tonumber)
+                 and .message.text != null
+                 and (.message.message_thread_id // 0) == $thread
+                 and .update_id > $sentinel)
+        | .update_id]
+      | max // 0
     ')
 
-    if [[ "$MSG_COUNT" -gt 0 ]]; then
-      NEW_TEXTS=$(echo "$UPDATES" | jq -r --arg cid "$TELEGRAM_CHAT_ID" '
-        [.result[] | select(.message.chat.id == ($cid | tonumber) and .message.text != null)]
-        | .[].message.text
-      ')
+    if [[ -n "$BATCH" ]]; then
       if [[ -n "$COLLECTED" ]]; then
         COLLECTED="${COLLECTED}
-${NEW_TEXTS}"
+${BATCH}"
       else
-        COLLECTED="$NEW_TEXTS"
+        COLLECTED="$BATCH"
+      fi
+      if (( MAX_ID > SENTINEL )); then
+        SENTINEL=$MAX_ID
       fi
-
       if [[ -z "$DEADLINE" ]]; then
         DEADLINE=$(( $(date +%s) + 10 ))
         echo "=== First message received, collecting for 10s... ===" >&2
       fi
     fi
 
-    NEW_LAST=$(echo "$UPDATES" | jq -r '.result[-1].update_id // empty')
-    if [[ -n "$NEW_LAST" ]]; then
-      OFFSET=$((NEW_LAST + 1))
+    if [[ -n "$DEADLINE" ]]; then
+      NOW=$(date +%s)
+      (( NOW >= DEADLINE )) && break
     fi
-  done
 
-  curl -s "${TELEGRAM_API}/getUpdates?offset=${OFFSET}" > /dev/null
+    sleep 2
+  done
 
   echo "$COLLECTED" > "$ANSWER_FILE"
   echo "=== Answer received from Telegram ===" >&2
@@ -110,12 +185,13 @@ ${NEW_TEXTS}"
   $LOOPX_BIN output --goto "apply-answer"
   exit 0
 else
-  # No question — notify and loop back to copy-prompt
+  # Terminal alert — route to General with the workflow label so it's clear
+  # which run is speaking. Per-run topic stays focused on the review dialog.
   curl -s -X POST "${TELEGRAM_API}/sendMessage" \
     -d chat_id="$TELEGRAM_CHAT_ID" \
-    -d text="Feedback applied. Ready for next review cycle." > /dev/null
+    --data-urlencode "text=[${ALERT_LABEL}] Feedback applied. Ready for next review cycle." > /dev/null
 
-  rm -f "$CLAUDE_OUTPUT_FILE" "$ROOT/.loopx/$LOOPX_WORKFLOW/.caller.tmp"
+  rm -f "$CLAUDE_OUTPUT_FILE" "$ROOT/.loopx/$LOOPX_WORKFLOW/.caller.tmp" "$ROOT/.loopx/$LOOPX_WORKFLOW/.session.tmp"
   echo "=== No questions. Ready for next review cycle. ===" >&2
   $LOOPX_BIN output --result "Feedback applied. Ready for next review cycle."
 fi
diff --git a/.loopx/shared/md-to-tg-html.mjs b/.loopx/shared/md-to-tg-html.mjs
new file mode 100644
index 0000000..593de40
--- /dev/null
+++ b/.loopx/shared/md-to-tg-html.mjs
@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// Markdown → Telegram-HTML converter for Claude Code output.
+// Not a full CommonMark parser; covers the subset Claude typically emits.
+// Telegram-supported tags: b, i, u, s, code, pre, a, blockquote, tg-spoiler.
+// Headings and lists aren't supported natively, so # → bold and - → •.
+
+import { readFileSync } from "node:fs";
+
+const input = readFileSync(0, "utf8");
+
+const placeholders = [];
+const ph = (s) => {
+  const token = `\x00${placeholders.length}\x00`;
+  placeholders.push(s);
+  return token;
+};
+
+const escHtml = (s) =>
+  s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+const escAttr = (s) =>
+  s.replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+
+let md = input;
+
+// Extract fenced code blocks first so inner content is not touched by other rules.
+md = md.replace(/```([a-zA-Z0-9_+-]*)\r?\n([\s\S]*?)```/g, (_m, lang, code) => {
+  const body = escHtml(code.replace(/\r?\n$/, ""));
+  const langAttr = lang ? ` class="language-${lang}"` : "";
+  return ph(`<pre><code${langAttr}>${body}</code></pre>`);
+});
+
+// Inline code.
+md = md.replace(/`([^`\n]+)`/g, (_m, code) => ph(`<code>${escHtml(code)}</code>`));
+
+// Escape the remaining document; from here on we emit tags directly.
+md = escHtml(md);
+
+// Links [text](url).
+md = md.replace(
+  /\[([^\]\n]+)\]\(([^)\s]+)\)/g,
+  (_m, text, url) => `<a href="${escAttr(url)}">${text}</a>`,
+);
+
+// Bold: **text** or __text__.
+md = md.replace(/\*\*([^*\n]+?)\*\*/g, "<b>$1</b>");
+md = md.replace(/(^|[^\w])__([^_\n]+?)__(?!\w)/g, "$1<b>$2</b>");
+
+// Italic: *text* / _text_ (avoid list markers and intra-word underscores).
+md = md.replace(/(^|[^*\w])\*([^*\n]+?)\*(?!\*)/g, "$1<i>$2</i>");
+md = md.replace(/(^|[^_\w])_([^_\n]+?)_(?!\w)/g, "$1<i>$2</i>");
+
+// Headings → bold (Telegram has no heading tag).
+md = md.replace(/^#{1,6}\s+(.+?)\s*#*$/gm, "<b>$1</b>");
+
+// Bullet list markers → •.
+md = md.replace(/^(\s*)[-*+]\s+/gm, "$1• ");
+
+// Horizontal rules.
+md = md.replace(/^\s*(?:-{3,}|\*{3,}|_{3,})\s*$/gm, "────────");
+
+// Blockquotes: wrap consecutive `> ` lines in a single <blockquote>.
+// (Escape pass has turned `>` into `&gt;`, so that's what we match.)
+md = md.replace(/(?:^&gt;\s?.*(?:\n|$))+/gm, (block) => {
+  const body = block
+    .replace(/^&gt;\s?/gm, "")
+    .replace(/\n$/, "");
+  return `<blockquote>${body}</blockquote>\n`;
+});
+
+// Restore extracted code spans.
+md = md.replace(/\x00(\d+)\x00/g, (_m, i) => placeholders[Number(i)]);
+
+process.stdout.write(md);
diff --git a/.loopx/shared/resolve-adr.sh b/.loopx/shared/resolve-adr.sh
new file mode 100755
index 0000000..7756870
--- /dev/null
+++ b/.loopx/shared/resolve-adr.sh
@@ -0,0 +1,36 @@
+#!/bin/bash
+# Resolves the ADR env var (e.g. ADR=4 or ADR=0004) to a full adr/NNNN-*.md path.
+# Outputs: "<zero-padded-number>\t<absolute-file-path>" on stdout.
+# Errors to stderr and exits 1 if ADR is unset, non-numeric, missing, or ambiguous.
+set -euo pipefail
+
+: "${LOOPX_PROJECT_ROOT:?LOOPX_PROJECT_ROOT must be set}"
+
+if [[ -z "${ADR:-}" ]]; then
+  echo "Error: ADR env var is required (e.g. ADR=4 or ADR=0004)" >&2
+  exit 1
+fi
+
+if ! [[ "$ADR" =~ ^[0-9]+$ ]]; then
+  echo "Error: ADR must be numeric (got '$ADR')" >&2
+  exit 1
+fi
+
+PADDED=$(printf '%04d' "$((10#$ADR))")
+
+shopt -s nullglob
+MATCHES=("$LOOPX_PROJECT_ROOT"/adr/"$PADDED"-*.md)
+shopt -u nullglob
+
+if [[ ${#MATCHES[@]} -eq 0 ]]; then
+  echo "Error: no ADR file found at adr/${PADDED}-*.md under $LOOPX_PROJECT_ROOT" >&2
+  exit 1
+fi
+
+if [[ ${#MATCHES[@]} -gt 1 ]]; then
+  echo "Error: multiple ADR files match adr/${PADDED}-*.md:" >&2
+  printf '  %s\n' "${MATCHES[@]}" >&2
+  exit 1
+fi
+
+printf '%s\t%s\n' "$PADDED" "${MATCHES[0]}"
diff --git a/.loopx/shared/send-api.ts b/.loopx/shared/send-api.ts
index 086ff22..882c33a 100644
--- a/.loopx/shared/send-api.ts
+++ b/.loopx/shared/send-api.ts
@@ -9,6 +9,7 @@ const THINKING = (process.env.GPT_PRO_THINKING ?? "medium") as
   | "medium"
   | "high"
   | "xhigh";
+const FLEX = process.env.OPENAI_FLEX === "true";
 
 if (!process.env.OPENAI_API_KEY) {
   console.error(
@@ -30,7 +31,7 @@ const prompt = readFileSync(PROMPT_FILE, "utf8");
 
 if (existsSync(FEEDBACK_FILE)) rmSync(FEEDBACK_FILE);
 
-const client = new OpenAI();
+const client = new OpenAI({ timeout: 60_000, maxRetries: 4 });
 
 // Resume a prior background response if one was persisted from an earlier run
 // that died before the response reached a terminal state. Background responses
@@ -54,26 +55,66 @@ if (existsSync(RESPONSE_ID_FILE)) {
 }
 
 if (!response) {
-  console.error(`requesting gpt-5.4-pro (thinking=${THINKING})...`);
+  console.error(
+    `requesting gpt-5.5-pro (thinking=${THINKING}${FLEX ? ", flex" : ""})...`,
+  );
   response = await client.responses.create({
-    model: "gpt-5.4-pro",
+    model: "gpt-5.5-pro",
     reasoning: { effort: THINKING },
     input: prompt,
     background: true,
+    prompt_cache_key: WORKFLOW,
+    prompt_cache_retention: "24h",
+    ...(FLEX ? { service_tier: "flex" } : {}),
   });
   writeFileSync(RESPONSE_ID_FILE, response.id);
   console.error(`submitted background response ${response.id}`);
 }
 
 const TERMINAL = new Set(["completed", "failed", "cancelled", "incomplete"]);
+// Each failed retrieve has already been through the SDK's 4 retries, so 20
+// consecutive failures represents tens of minutes of sustained OpenAI
+// unavailability — wider than any single inference window.
+const MAX_POLL_FAILURES = 20;
+// Inference can take up to ~30 min at xhigh thinking; 1 h bounds worst-case
+// hangs where a response is accepted but never transitions to terminal.
+// Measured from response.created_at so resumes don't reset the clock.
+const DEADLINE_SECS = 60 * 60;
 let lastStatus: string | undefined;
+let pollFailures = 0;
 while (!TERMINAL.has(response.status ?? "")) {
+  const ageSecs = Math.floor(Date.now() / 1000) - response.created_at;
+  if (ageSecs > DEADLINE_SECS) {
+    console.error(
+      `${response.id} exceeded ${DEADLINE_SECS / 60}m deadline (age ${ageSecs}s, status ${response.status}); cancelling`,
+    );
+    try {
+      await client.responses.cancel(response.id);
+    } catch (err: any) {
+      const status = err?.status ?? err?.code ?? "error";
+      console.error(`cancel ${response.id} failed (${status})`);
+    }
+    rmSync(RESPONSE_ID_FILE, { force: true });
+    throw new Error(
+      `gpt-5.5-pro response ${response.id} did not complete within ${DEADLINE_SECS / 60} minutes (last status: ${response.status ?? "unknown"})`,
+    );
+  }
   if (response.status !== lastStatus) {
     console.error(`waiting for ${response.id} (${response.status})...`);
     lastStatus = response.status ?? undefined;
   }
   await new Promise((r) => setTimeout(r, 2000));
-  response = await client.responses.retrieve(response.id);
+  try {
+    response = await client.responses.retrieve(response.id);
+    pollFailures = 0;
+  } catch (err: any) {
+    pollFailures++;
+    const status = err?.status ?? err?.code ?? "error";
+    console.error(
+      `poll ${response.id} failed (${status}); retry ${pollFailures}/${MAX_POLL_FAILURES}`,
+    );
+    if (pollFailures >= MAX_POLL_FAILURES) throw err;
+  }
 }
 
 if (response.status !== "completed") {
@@ -84,7 +125,16 @@ if (response.status !== "completed") {
         ? `: ${response.error.message}`
         : "";
   throw new Error(
-    `gpt-5.4-pro response ${response.id} ended in status ${response.status}${detail}`,
+    `gpt-5.5-pro response ${response.id} ended in status ${response.status}${detail}`,
+  );
+}
+
+const cachedTokens = response.usage?.input_tokens_details?.cached_tokens ?? 0;
+const inputTokens = response.usage?.input_tokens ?? 0;
+if (inputTokens > 0) {
+  const pct = Math.round((100 * cachedTokens) / inputTokens);
+  console.error(
+    `tokens: input=${inputTokens} cached=${cachedTokens} (${pct}%) output=${response.usage?.output_tokens ?? 0}`,
   );
 }
 
@@ -98,13 +148,16 @@ const answer =
     .join("\n");
 
 if (!answer) {
-  throw new Error("gpt-5.4-pro returned no output text");
+  throw new Error("gpt-5.5-pro returned no output text");
 }
 
 writeFileSync(FEEDBACK_FILE, answer);
-rmSync(PROMPT_FILE);
-if (existsSync(RESPONSE_ID_FILE)) rmSync(RESPONSE_ID_FILE);
-console.error("=== Feedback received from GPT-5.4-Pro ===");
+// force:true — external cleanup (reinstall, git clean, sibling workflow) can
+// remove these scratch files mid-run; crashing here would skip the goto to
+// check-feedback-done and strand the loop.
+rmSync(PROMPT_FILE, { force: true });
+rmSync(RESPONSE_ID_FILE, { force: true });
+console.error("=== Feedback received from GPT-5.5-Pro ===");
 
 execFileSync(BIN, ["output", "--goto", "check-feedback-done"], {
   stdio: "inherit",
diff --git a/.loopx/shared/send-batch.ts b/.loopx/shared/send-batch.ts
index 11cd783..bdf40c8 100644
--- a/.loopx/shared/send-batch.ts
+++ b/.loopx/shared/send-batch.ts
@@ -30,27 +30,32 @@ const prompt = readFileSync(PROMPT_FILE, "utf8");
 
 if (existsSync(FEEDBACK_FILE)) rmSync(FEEDBACK_FILE);
 
-const client = new OpenAI();
+const client = new OpenAI({ timeout: 60_000, maxRetries: 4 });
 
 const batchLine = JSON.stringify({
-  custom_id: `gpt54-${randomUUID()}`,
+  custom_id: `gpt55-${randomUUID()}`,
   method: "POST",
   url: "/v1/responses",
   body: {
-    model: "gpt-5.4-pro",
+    model: "gpt-5.5-pro",
     reasoning: { effort: THINKING },
     input: prompt,
+    prompt_cache_key: WORKFLOW,
+    prompt_cache_retention: "24h",
   },
 });
 
-const inputFile = await client.files.create({
-  file: await toFile(
-    Buffer.from(batchLine + "\n", "utf8"),
-    `batch-${Date.now()}.jsonl`,
-    { type: "application/x-ndjson" },
-  ),
-  purpose: "batch",
-});
+const inputFile = await client.files.create(
+  {
+    file: await toFile(
+      Buffer.from(batchLine + "\n", "utf8"),
+      `batch-${Date.now()}.jsonl`,
+      { type: "application/x-ndjson" },
+    ),
+    purpose: "batch",
+  },
+  { timeout: 300_000 },
+);
 
 const batch = await client.batches.create({
   input_file_id: inputFile.id,
@@ -62,13 +67,29 @@ console.error(`submitted batch: ${batch.id}`);
 
 let b = batch;
 let lastStatus: string | undefined;
+// Each failed retrieve has already been through the SDK's 4 retries, so 20
+// consecutive failures represents tens of minutes of sustained OpenAI
+// unavailability. Crashing would forfeit the batch and double-submit next run.
+const MAX_POLL_FAILURES = 20;
+let pollFailures = 0;
 while (
   !b.output_file_id &&
   !b.error_file_id &&
   !["failed", "expired", "cancelled"].includes(b.status)
 ) {
   await new Promise((r) => setTimeout(r, 2000));
-  b = await client.batches.retrieve(batch.id);
+  try {
+    b = await client.batches.retrieve(batch.id);
+    pollFailures = 0;
+  } catch (err: any) {
+    pollFailures++;
+    const status = err?.status ?? err?.code ?? "error";
+    console.error(
+      `poll batch ${batch.id} failed (${status}); retry ${pollFailures}/${MAX_POLL_FAILURES}`,
+    );
+    if (pollFailures >= MAX_POLL_FAILURES) throw err;
+    continue;
+  }
   if (b.status !== lastStatus) {
     console.error(`waiting for batch ${b.id} (${b.status})...`);
     lastStatus = b.status;
@@ -76,14 +97,18 @@ while (
 }
 
 if (b.error_file_id) {
-  const err = await (await client.files.content(b.error_file_id)).text();
+  const err = await (
+    await client.files.content(b.error_file_id, { timeout: 300_000 })
+  ).text();
   throw new Error(`Batch error: ${err}`);
 }
 if (!b.output_file_id) {
   throw new Error(`Batch ${batch.id} ended in status ${b.status}`);
 }
 
-const outText = await (await client.files.content(b.output_file_id)).text();
+const outText = await (
+  await client.files.content(b.output_file_id, { timeout: 300_000 })
+).text();
 const line = JSON.parse(outText.trim().split(/\r?\n/)[0]);
 if (line.error) throw new Error(`Batch error: ${line.error.message}`);
 
@@ -98,8 +123,11 @@ const answer =
     .join("\n");
 
 writeFileSync(FEEDBACK_FILE, answer);
-rmSync(PROMPT_FILE);
-console.error("=== Feedback received from GPT-5.4-Pro ===");
+// force:true — external cleanup (reinstall, git clean, sibling workflow) can
+// remove the prompt file mid-run; crashing here would skip the goto to
+// check-feedback-done and strand the loop.
+rmSync(PROMPT_FILE, { force: true });
+console.error("=== Feedback received from GPT-5.5-Pro ===");
 
 execFileSync(BIN, ["output", "--goto", "check-feedback-done"], {
   stdio: "inherit",
diff --git a/.loopx/shared/send-codex.sh b/.loopx/shared/send-codex.sh
index 5fe3a97..e2268b2 100755
--- a/.loopx/shared/send-codex.sh
+++ b/.loopx/shared/send-codex.sh
@@ -18,22 +18,34 @@ fi
 echo "" >&2
 echo "=== Invoking codex CLI ===" >&2
 
-rm -f "$FEEDBACK_FILE"
+STDERR_LOG="$ROOT/.loopx/$LOOPX_WORKFLOW/.codex-stderr.tmp"
+rm -f "$FEEDBACK_FILE" "$STDERR_LOG"
 
+set +e
 codex exec - \
   --skip-git-repo-check \
   --sandbox read-only \
   --color never \
   --output-last-message "$FEEDBACK_FILE" \
-  < "$PROMPT_FILE" >/dev/null
+  < "$PROMPT_FILE" >/dev/null 2>"$STDERR_LOG"
+CODEX_STATUS=$?
+set -e
 
 rm -f "$PROMPT_FILE"
 
-if [[ ! -s "$FEEDBACK_FILE" ]]; then
-  echo "Error: codex produced no feedback" >&2
+if [[ $CODEX_STATUS -ne 0 || ! -s "$FEEDBACK_FILE" ]]; then
+  echo "Error: codex exec failed (exit=$CODEX_STATUS) or produced no feedback" >&2
+  if [[ -s "$STDERR_LOG" ]]; then
+    echo "--- codex stderr ---" >&2
+    cat "$STDERR_LOG" >&2
+    echo "--- end codex stderr ---" >&2
+  fi
+  rm -f "$STDERR_LOG"
   exit 1
 fi
 
+rm -f "$STDERR_LOG"
+
 echo "=== Feedback received from codex ===" >&2
 echo "--- Begin feedback ---" >&2
 cat "$FEEDBACK_FILE" >&2
diff --git a/.loopx/shared/send-telegram.sh b/.loopx/shared/send-telegram.sh
index 822cba5..6497c1f 100755
--- a/.loopx/shared/send-telegram.sh
+++ b/.loopx/shared/send-telegram.sh
@@ -1,99 +1,123 @@
 #!/bin/bash
 set -euo pipefail
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=./telegram-lib.sh
+source "$SCRIPT_DIR/telegram-lib.sh"
+
 ROOT="$LOOPX_PROJECT_ROOT"
 PROMPT_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.prompt.tmp"
 FEEDBACK_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.feedback.tmp"
 
-: "${TELEGRAM_BOT_TOKEN:?TELEGRAM_BOT_TOKEN env var is required}"
-: "${TELEGRAM_CHAT_ID:?TELEGRAM_CHAT_ID env var is required}"
-
 if [[ ! -s "$PROMPT_FILE" ]]; then
   echo "Error: prompt file not found at $PROMPT_FILE" >&2
   exit 1
 fi
 
-TELEGRAM_API="https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}"
-
-# Flush old updates to get current offset
-FLUSH_RESPONSE=$(curl -s "${TELEGRAM_API}/getUpdates?offset=-1")
-LAST_UPDATE_ID=$(echo "$FLUSH_RESPONSE" | jq -r '.result[-1].update_id // empty')
-if [[ -n "$LAST_UPDATE_ID" ]]; then
-  OFFSET=$((LAST_UPDATE_ID + 1))
-else
-  OFFSET=0
+TOPIC_NAME=$(tg_topic_name)
+
+send_prompt() {
+  curl -s -X POST "${TELEGRAM_API}/sendDocument" \
+    -F chat_id="$TELEGRAM_CHAT_ID" \
+    -F message_thread_id="$1" \
+    -F document=@"$PROMPT_FILE;filename=review-prompt.md" \
+    -F caption="Review prompt — reply with your feedback"
+}
+
+# Watermark: highest update_id currently in the queue. Set BEFORE sending so a
+# near-instant reply (update_id arriving during the sendDocument roundtrip) is
+# still newer than SENTINEL and isn't filtered out. offset=-1 peeks the tail
+# without advancing the global confirmation pointer — confirming via a positive
+# offset would delete updates queued for other parallel runs of this bot.
+SENTINEL=$(curl -s "${TELEGRAM_API}/getUpdates?offset=-1&limit=1" | jq -r '.result[-1].update_id // 0')
+
+THREAD_ID=$(tg_resolve_topic_id "$TOPIC_NAME")
+
+SEND_RESPONSE=$(send_prompt "$THREAD_ID")
+if [[ "$(echo "$SEND_RESPONSE" | jq -r '.ok')" != "true" ]]; then
+  DESC=$(echo "$SEND_RESPONSE" | jq -r '.description // ""')
+  # User may have closed or deleted the topic between runs — invalidate cache and recreate.
+  if tg_is_stale_thread_error "$DESC"; then
+    echo "Warning: cached topic $THREAD_ID no longer usable — recreating..." >&2
+    tg_forget_topic "$TOPIC_NAME"
+    THREAD_ID=$(tg_resolve_topic_id "$TOPIC_NAME")
+    SEND_RESPONSE=$(send_prompt "$THREAD_ID")
+  fi
 fi
-
-# Send the prompt as a document attachment
-SEND_RESPONSE=$(curl -s -X POST "${TELEGRAM_API}/sendDocument" \
-  -F chat_id="$TELEGRAM_CHAT_ID" \
-  -F document=@"$PROMPT_FILE;filename=review-prompt.md" \
-  -F caption="Review prompt — reply with your feedback")
-
-SENT_OK=$(echo "$SEND_RESPONSE" | jq -r '.ok')
-if [[ "$SENT_OK" != "true" ]]; then
+if [[ "$(echo "$SEND_RESPONSE" | jq -r '.ok')" != "true" ]]; then
   echo "Error: Failed to send Telegram message: $SEND_RESPONSE" >&2
   rm -f "$PROMPT_FILE"
   exit 1
 fi
-
 rm -f "$PROMPT_FILE"
 
 echo "" >&2
-echo "=== Prompt sent to Telegram ===" >&2
-echo "Reply in the Telegram chat with your feedback." >&2
+echo "=== Prompt sent to Telegram topic '$TOPIC_NAME' (thread $THREAD_ID) ===" >&2
+echo "Reply in that topic with your feedback." >&2
 echo "Waiting for reply..." >&2
 
-# Long-poll for a reply, collecting split messages over a 10s window
 COLLECTED=""
 DEADLINE=""
 
 while true; do
-  # After first message arrives, switch to short polls and enforce deadline
-  if [[ -n "$DEADLINE" ]]; then
-    NOW=$(date +%s)
-    if [[ $NOW -ge $DEADLINE ]]; then
-      break
-    fi
-    POLL_TIMEOUT=2
-  else
-    POLL_TIMEOUT=30
+  # Negative offset = read tail without advancing the global confirmation
+  # pointer. Every parallel run sees the same updates and each filters for its
+  # own thread_id. We always poll once per iteration, then check the deadline,
+  # so the final poll covers the full 10s window (checking before polling
+  # would drop messages arriving in the last sleep interval).
+  UPDATES=$(curl -s "${TELEGRAM_API}/getUpdates?offset=-100&limit=100")
+  if [[ "$(echo "$UPDATES" | jq -r '.ok // false')" != "true" ]]; then
+    sleep 2
+    continue
   fi
 
-  UPDATES=$(curl -s "${TELEGRAM_API}/getUpdates?offset=${OFFSET}&timeout=${POLL_TIMEOUT}")
-
-  MSG_COUNT=$(echo "$UPDATES" | jq --arg cid "$TELEGRAM_CHAT_ID" '
-    [.result[] | select(.message.chat.id == ($cid | tonumber) and .message.text != null)] | length
+  BATCH=$(echo "$UPDATES" | jq -r \
+    --arg cid "$TELEGRAM_CHAT_ID" \
+    --argjson thread "$THREAD_ID" \
+    --argjson sentinel "$SENTINEL" '
+    [.result[]
+      | select(.message.chat.id == ($cid|tonumber)
+               and .message.text != null
+               and (.message.message_thread_id // 0) == $thread
+               and .update_id > $sentinel)]
+    | map(.message.text) | join("\n")
+  ')
+  MAX_ID=$(echo "$UPDATES" | jq -r \
+    --arg cid "$TELEGRAM_CHAT_ID" \
+    --argjson thread "$THREAD_ID" \
+    --argjson sentinel "$SENTINEL" '
+    [.result[]
+      | select(.message.chat.id == ($cid|tonumber)
+               and .message.text != null
+               and (.message.message_thread_id // 0) == $thread
+               and .update_id > $sentinel)
+      | .update_id]
+    | max // 0
   ')
 
-  if [[ "$MSG_COUNT" -gt 0 ]]; then
-    NEW_TEXTS=$(echo "$UPDATES" | jq -r --arg cid "$TELEGRAM_CHAT_ID" '
-      [.result[] | select(.message.chat.id == ($cid | tonumber) and .message.text != null)]
-      | .[].message.text
-    ')
+  if [[ -n "$BATCH" ]]; then
     if [[ -n "$COLLECTED" ]]; then
       COLLECTED="${COLLECTED}
-${NEW_TEXTS}"
+${BATCH}"
     else
-      COLLECTED="$NEW_TEXTS"
+      COLLECTED="$BATCH"
+    fi
+    if (( MAX_ID > SENTINEL )); then
+      SENTINEL=$MAX_ID
     fi
-
-    # Start 10s collection window on first message
     if [[ -z "$DEADLINE" ]]; then
       DEADLINE=$(( $(date +%s) + 10 ))
       echo "=== First message received, collecting for 10s... ===" >&2
     fi
   fi
 
-  # Advance offset past all updates
-  NEW_LAST=$(echo "$UPDATES" | jq -r '.result[-1].update_id // empty')
-  if [[ -n "$NEW_LAST" ]]; then
-    OFFSET=$((NEW_LAST + 1))
+  if [[ -n "$DEADLINE" ]]; then
+    NOW=$(date +%s)
+    (( NOW >= DEADLINE )) && break
   fi
-done
 
-# Acknowledge all collected updates
-curl -s "${TELEGRAM_API}/getUpdates?offset=${OFFSET}" > /dev/null
+  sleep 2
+done
 
 echo "$COLLECTED" > "$FEEDBACK_FILE"
 echo "=== Feedback received from Telegram ===" >&2
diff --git a/.loopx/shared/telegram-lib.sh b/.loopx/shared/telegram-lib.sh
new file mode 100644
index 0000000..cd17d49
--- /dev/null
+++ b/.loopx/shared/telegram-lib.sh
@@ -0,0 +1,113 @@
+# Shared telegram helpers. Source (don't exec) this file from shared/ scripts
+# that need to resolve per-run forum topics, post into them, or emit workflow-
+# labeled alerts to General.
+#
+# Required env: TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID, LOOPX_PROJECT_ROOT, LOOPX_WORKFLOW.
+# Exports: TELEGRAM_API plus the tg_* functions below.
+
+: "${TELEGRAM_BOT_TOKEN:?TELEGRAM_BOT_TOKEN env var is required}"
+: "${TELEGRAM_CHAT_ID:?TELEGRAM_CHAT_ID env var is required}"
+: "${LOOPX_PROJECT_ROOT:?LOOPX_PROJECT_ROOT env var is required}"
+: "${LOOPX_WORKFLOW:?LOOPX_WORKFLOW env var is required}"
+
+TELEGRAM_API="https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}"
+
+_TG_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# The caller workflow that owns this review cycle. When shared/ scripts run as
+# LOOPX_WORKFLOW=shared (via shared:dispatch/check-question/apply-answer), the
+# caller's name lives in .caller.tmp, written by the caller's index.sh. When
+# running directly under a caller workflow, LOOPX_WORKFLOW is already the
+# caller.
+tg_caller_workflow() {
+  local caller_file="$LOOPX_PROJECT_ROOT/.loopx/$LOOPX_WORKFLOW/.caller.tmp"
+  if [[ -s "$caller_file" ]]; then
+    tr -d '\n' < "$caller_file"
+  else
+    printf '%s' "$LOOPX_WORKFLOW"
+  fi
+}
+
+# Forum topic name: "<repo> / <caller> [ / ADR-NNNN ]". One topic per (repo,
+# caller, optional ADR) so parallel runs in different repos or on different
+# ADRs don't collide.
+tg_topic_name() {
+  local owner name padded resolved
+  owner=$(tg_caller_workflow)
+  name="$(basename "$LOOPX_PROJECT_ROOT") / $owner"
+  if [[ -n "${ADR:-}" ]]; then
+    if resolved=$("$_TG_LIB_DIR/resolve-adr.sh" 2>/dev/null); then
+      padded=$(printf '%s' "$resolved" | cut -f1)
+      name="$name / ADR-$padded"
+    fi
+  fi
+  printf '%s' "$name"
+}
+
+# Short label for alerts routed to General so it's obvious which run is
+# speaking: "<repo> / <caller>[ / ADR-NNNN]".
+tg_alert_label() {
+  tg_topic_name
+}
+
+_TG_TOKEN_HASH=$(printf '%s' "$TELEGRAM_BOT_TOKEN" | sha256sum | cut -c1-12)
+_TG_CACHE_DIR="${XDG_CACHE_HOME:-$HOME/.cache}/loopx-telegram"
+mkdir -p "$_TG_CACHE_DIR"
+_TG_CACHE_FILE="$_TG_CACHE_DIR/topics-$_TG_TOKEN_HASH.json"
+_TG_LOCK_FILE="$_TG_CACHE_DIR/topics-$_TG_TOKEN_HASH.lock"
+
+# Resolve (and if needed create) the message_thread_id for a topic name. Echoes
+# the numeric id on stdout. Flocked so concurrent first-runs don't double-create
+# the same topic.
+tg_resolve_topic_id() {
+  local topic="$1"
+  local cache_key="${TELEGRAM_CHAT_ID}|${topic}"
+  (
+    exec 9>"$_TG_LOCK_FILE"
+    flock -x 9
+    [[ -f "$_TG_CACHE_FILE" ]] || echo '{}' > "$_TG_CACHE_FILE"
+    local id resp
+    id=$(jq -r --arg k "$cache_key" '.[$k] // empty' "$_TG_CACHE_FILE")
+    if [[ -z "$id" ]]; then
+      resp=$(curl -s -X POST "${TELEGRAM_API}/createForumTopic" \
+        --data-urlencode "chat_id=$TELEGRAM_CHAT_ID" \
+        --data-urlencode "name=$topic")
+      if [[ "$(echo "$resp" | jq -r '.ok')" != "true" ]]; then
+        echo "Error: failed to create Telegram topic '$topic': $resp" >&2
+        echo "Hint: TELEGRAM_CHAT_ID must point to a forum-enabled supergroup, and the bot must have 'Manage Topics' admin rights." >&2
+        exit 1
+      fi
+      id=$(echo "$resp" | jq -r '.result.message_thread_id // empty')
+      if [[ -z "$id" ]]; then
+        echo "Error: createForumTopic returned ok but no message_thread_id: $resp" >&2
+        exit 1
+      fi
+      jq --arg k "$cache_key" --argjson id "$id" '. + {($k): $id}' "$_TG_CACHE_FILE" > "$_TG_CACHE_FILE.tmp"
+      mv "$_TG_CACHE_FILE.tmp" "$_TG_CACHE_FILE"
+    fi
+    printf '%s' "$id"
+  )
+}
+
+# Drop a topic from the cache so the next tg_resolve_topic_id recreates it.
+# Call this when a send fails with "thread not found" / closed / deleted.
+tg_forget_topic() {
+  local topic="$1"
+  local cache_key="${TELEGRAM_CHAT_ID}|${topic}"
+  (
+    exec 9>"$_TG_LOCK_FILE"
+    flock -x 9
+    [[ -f "$_TG_CACHE_FILE" ]] || exit 0
+    jq --arg k "$cache_key" 'del(.[$k])' "$_TG_CACHE_FILE" > "$_TG_CACHE_FILE.tmp"
+    mv "$_TG_CACHE_FILE.tmp" "$_TG_CACHE_FILE"
+  )
+}
+
+# True if a sendMessage/sendDocument error description indicates the cached
+# thread_id is no longer usable and should be recreated.
+tg_is_stale_thread_error() {
+  local desc="$1"
+  [[ "$desc" == *"thread not found"* ]] \
+    || [[ "$desc" == *"TOPIC_DELETED"* ]] \
+    || [[ "$desc" == *"topic closed"* ]]
+}
diff --git a/.loopx/spec-test-adr/apply-feedback.sh b/.loopx/spec-test-adr/apply-feedback.sh
index af7ac81..3c39219 100755
--- a/.loopx/spec-test-adr/apply-feedback.sh
+++ b/.loopx/spec-test-adr/apply-feedback.sh
@@ -5,6 +5,7 @@ ROOT="$LOOPX_PROJECT_ROOT"
 SHARED_DIR="$ROOT/.loopx/shared"
 FEEDBACK_FILE="$SHARED_DIR/.feedback.tmp"
 CLAUDE_OUTPUT_FILE="$SHARED_DIR/.claude-output.tmp"
+SESSION_FILE="$SHARED_DIR/.session.tmp"
 
 if [[ ! -f "$FEEDBACK_FILE" ]]; then
   echo "Error: No feedback file found at $FEEDBACK_FILE" >&2
@@ -13,25 +14,19 @@ fi
 
 FEEDBACK=$(cat "$FEEDBACK_FILE")
 
-ADR_0002=$(cat "$ROOT/adr/0002-run-subcommand.md")
-SPEC=$(cat "$ROOT/SPEC.md")
-TEST_SPEC=$(cat "$ROOT/TEST-SPEC.md")
+RESOLVED=$("$SHARED_DIR/resolve-adr.sh")
+IFS=$'\t' read -r ADR_NUM ADR_FILE <<< "$RESOLVED"
+ADR_REL="adr/$(basename "$ADR_FILE")"
 
-PROMPT="ADR-0002 has been accepted and SPEC.md has already been updated to incorporate its changes (per the ADR process in ADR-0001). I am now updating TEST-SPEC.md to cover the new and changed spec behavior introduced by ADR-0002. I received the following feedback on the current state of TEST-SPEC.md. Apply this feedback by updating TEST-SPEC.md only — do not modify SPEC.md or ADR-0002, they are read-only references in this cycle. ADR-0002 and the updated SPEC.md are the authoritative sources for what TEST-SPEC.md should cover. If there is any ambiguity about my intentions, ask me clarifying questions. Think critically about this feedback and push back if warranted. After you finish, commit and push.
-
-adr/0002-run-subcommand.md (accepted — read-only reference):
-$ADR_0002
-
-SPEC.md (already updated for ADR-0002 — read-only reference):
-$SPEC
-
-Current TEST-SPEC.md (target of updates):
-$TEST_SPEC
+PROMPT="ADR-$ADR_NUM ($ADR_REL) has been accepted and SPEC.md has already been updated to incorporate its changes (per the ADR process in adr/0001-adr-process.md). I am now updating TEST-SPEC.md to cover the new and changed spec behavior introduced by ADR-$ADR_NUM. I received the following feedback on the current state of TEST-SPEC.md. Apply this feedback by updating TEST-SPEC.md only — do not modify SPEC.md or ADR-$ADR_NUM, they are read-only references in this cycle. ADR-$ADR_NUM and the updated SPEC.md are the authoritative sources for what TEST-SPEC.md should cover. If there is any ambiguity about my intentions, ask me clarifying questions. When you ask questions, ask only one at a time and wait for my answer before asking the next — do not batch multiple questions together. I have not read the feedback, I only pasted it in, so phrase each question to stand on its own: include the relevant context or quote from the feedback so I can answer without having to go read it. Think critically about this feedback and push back if warranted. After you finish, commit and push.
 
 Feedback:
 $FEEDBACK"
 
-CLAUDE_OUTPUT=$(echo "$PROMPT" | claude --dangerously-skip-permissions -p 2>/dev/null)
+SESSION_ID=$(uuidgen | tr '[:upper:]' '[:lower:]')
+echo "$SESSION_ID" > "$SESSION_FILE"
+
+CLAUDE_OUTPUT=$(echo "$PROMPT" | claude --dangerously-skip-permissions --session-id "$SESSION_ID" -p 2>/dev/null)
 
 rm -f "$FEEDBACK_FILE"
 echo "$CLAUDE_OUTPUT" > "$CLAUDE_OUTPUT_FILE"
diff --git a/.loopx/spec-test-adr/index.sh b/.loopx/spec-test-adr/index.sh
index cc4f82c..595c73b 100755
--- a/.loopx/spec-test-adr/index.sh
+++ b/.loopx/spec-test-adr/index.sh
@@ -3,7 +3,6 @@ set -euo pipefail
 
 ROOT="$LOOPX_PROJECT_ROOT"
 ADR_0001="$ROOT/adr/0001-adr-process.md"
-ADR_0002="$ROOT/adr/0002-run-subcommand.md"
 SPEC="$ROOT/SPEC.md"
 TEST_SPEC="$ROOT/TEST-SPEC.md"
 SHARED_DIR="$ROOT/.loopx/shared"
@@ -20,11 +19,6 @@ if [[ ! -f "$ADR_0001" ]]; then
   exit 1
 fi
 
-if [[ ! -f "$ADR_0002" ]]; then
-  echo "Error: adr/0002-run-subcommand.md not found" >&2
-  exit 1
-fi
-
 if [[ ! -f "$SPEC" ]]; then
   echo "Error: SPEC.md not found" >&2
   exit 1
@@ -35,17 +29,21 @@ if [[ ! -f "$TEST_SPEC" ]]; then
   exit 1
 fi
 
+RESOLVED=$("$SHARED_DIR/resolve-adr.sh")
+IFS=$'\t' read -r ADR_NUM ADR_FILE <<< "$RESOLVED"
+ADR_REL="adr/$(basename "$ADR_FILE")"
+
 echo "$LOOPX_WORKFLOW" > "$CALLER_FILE"
 
 cat <<PROMPT > "$PROMPT_FILE"
-ADR 0002 has been accepted and SPEC.md has already been updated to incorporate its changes (ADR status: "Spec Updated"). Per the ADR process in ADR-0001, the next step is to update TEST-SPEC.md to cover the new and changed spec behavior introduced by ADR-0002. In this cycle, TEST-SPEC.md is the only file that should be modified — SPEC.md and ADR-0002 are read-only references.
+ADR $ADR_NUM has been accepted and SPEC.md has already been updated to incorporate its changes (ADR status: "Spec Updated"). Per the ADR process in ADR-0001, the next step is to update TEST-SPEC.md to cover the new and changed spec behavior introduced by ADR-$ADR_NUM. In this cycle, TEST-SPEC.md is the only file that should be modified — SPEC.md and ADR-$ADR_NUM are read-only references.
 
-Review the current TEST-SPEC.md against the updated SPEC.md and ADR-0002, and let me know whether TEST-SPEC.md already covers the ADR-0002 changes correctly and completely, or what needs to be added, changed, or removed. Do not suggest changes to SPEC.md or ADR-0002 — if something looks wrong in those, flag it but do not act on it.
+Review the current TEST-SPEC.md against the updated SPEC.md and ADR-$ADR_NUM, and let me know whether TEST-SPEC.md already covers the ADR-$ADR_NUM changes correctly and completely, or what needs to be added, changed, or removed. Do not suggest changes to SPEC.md or ADR-$ADR_NUM — if something looks wrong in those, flag it but do not act on it.
 
-adr/0002-run-subcommand.md (accepted — read-only reference):
-$(cat "$ADR_0002")
+$ADR_REL (accepted — read-only reference):
+$(cat "$ADR_FILE")
 
-SPEC.md (already updated for ADR-0002 — read-only reference):
+SPEC.md (already updated for ADR-$ADR_NUM — read-only reference):
 $(cat "$SPEC")
 
 TEST-SPEC.md (target of updates):
diff --git a/SPEC-PROBLEMS.md b/SPEC-PROBLEMS.md
index 96ae7b7..6d3658b 100644
--- a/SPEC-PROBLEMS.md
+++ b/SPEC-PROBLEMS.md
@@ -1,13 +1,51 @@
-## T-INST-GLOBAL-01a: Bun global install `import "loopx"` resolution
+# SPEC Problems
 
-The npm package is named `loop-extender` (not `loopx`). For local installs, a symlink `node_modules/loopx → dist/` makes `import "loopx"` work via NODE_PATH. For global installs (`npm install -g`), the package is installed as `<prefix>/lib/node_modules/loop-extender/` — there is no `loopx` symlink.
+This file tracks ambiguities, gaps, or under-specified clauses in SPEC.md that prevent TEST-SPEC.md from covering the behavior cleanly. Each entry is scoped to a specific ADR cycle. Resolve in a follow-up cycle by updating SPEC.md and removing the entry; delete the file when no entries remain.
 
-Under Node.js, the custom module loader (`--import` with `module.register()`) intercepts the bare specifier `"loopx"` regardless of directory names. Under Bun, the only resolution mechanism is NODE_PATH, which requires a directory named `loopx` somewhere in the search path.
+## ADR-0004
 
-**Impact**: T-INST-GLOBAL-01a (Bun global install with `import { output } from "loopx"`) cannot work until the package is either renamed to `loopx` or a postinstall hook creates a `loopx` symlink in the global node_modules. The test currently uses a bash script instead of a TS script with imports.
+### P-0004-01 — Abort-after-final-yield vs. already-observed consumer `.return()` / `.throw()` before settlement
 
-**Resolution**: Rename the npm package to `loopx`, or add a `postinstall` script that creates a symlink from the package directory to a `loopx` entry in the parent node_modules directory.
+**Where.** SPEC §9.3 ("Abort after final yield") and §7.2 ("Terminal-outcome precedence"). ADR-0004 §"Programmatic API · Termination" line "Abort after the final yielded `Output` still wins until generator settlement."
 
-## T-PARSE-20a: Ambiguous spec wording about "first iteration"
+**Problem.** SPEC §9.3 says: "An `AbortSignal` that aborts after the final `Output` has been yielded ... but before the generator settles via `{ done: true }` produces the abort error on the next generator interaction — `g.next()`, `.return()`, or `.throw()`." This text is clear when the abort is observed *before* the next consumer interaction begins. It is not clear what wins when the consumer has *already* invoked `.return()` / `.throw()` after the final yield, loopx has observed that interaction first and entered the cleanup routine, and abort then arrives during cleanup before the generator settles.
 
-TEST-SPEC says: "the generator throws an error on the first iteration." This is misleading — the generator yields the first iteration's Output (which contains `{goto: ""}`) and then throws on the *next* `.next()` call when it tries to resolve the empty goto target. The `iterationCount` is 1 (one yield) before the error, not 0. The spec wording should say "throws an error after the first iteration yields" or "throws during goto resolution following the first iteration."
+Two readings are reasonable:
+
+1. **§9.3 is an explicit precedence rule that holds until settlement.** Abort after final yield wins over any non-settlement outcome until `{ done: true }`, including an already-observed but not-yet-settled consumer `.return()` / `.throw()`. ADR-0004's phrasing — "abort still wins until generator settlement" — supports this reading.
+
+2. **§9.3 only applies when abort precedes the next interaction.** Once a consumer interaction has been observed first, the §7.2 first-observed-wins residual rule applies and the consumer interaction's outcome (silent clean completion under §9.1's no-active-child swallow rule) survives a later abort that races during cleanup.
+
+The SPEC text alone does not disambiguate.
+
+**Impact on TEST-SPEC.** T-TMP-38d2 (post-final-yield consumer `.throw()` observed first × racing abort during cleanup) currently picks reading 2 and pins the surfaced outcome to `{ done: true }`. Until SPEC clarifies, the surfaced-outcome assertion is contested; T-TMP-38d2 has been relaxed to assert only the cleanup-idempotence and warning-cardinality contract that *is* pinned by SPEC §7.2. Symmetric concerns apply to a corresponding `.return()`-first × abort-second post-final-yield variant, should one be added.
+
+**Resolution requested.** Either:
+- Amend §9.3 to state explicitly that the abort-after-final-yield precedence rule holds until settlement and displaces any already-observed but not-yet-settled consumer `.return()` / `.throw()` outcome, or
+- Amend §9.3 / §7.2 to state explicitly that once a post-final-yield `.return()` / `.throw()` is observed first, later aborts before settlement fall back to the §7.2 first-observed-wins residual rule.
+
+Either resolution unblocks pinning the surfaced-outcome axis for T-TMP-38d2 (and any symmetric `.return()` variant).
+
+---
+
+### P-0004-02 — Outer `RunOptions` inherited-field semantics
+
+**Where.** SPEC §9.5 (`RunOptions` shape), §9.1 / §9.2 ("Option-snapshot timing"). ADR-0004 §"Programmatic API · `RunOptions.env`".
+
+**Problem.** SPEC §9.5 explicitly specifies own-enumerable-only semantics for `options.env` ("Symbol-keyed, non-enumerable, and inherited properties are ignored"). It is silent on whether the *outer* `options` object's recognized fields (`signal`, `cwd`, `envFile`, `maxIterations`, `env`) are read via ordinary JS property access (which honors inherited properties) or via own-enumerable-only access matching the inner `env` rule.
+
+Existing behavior implied by adjacent rules pulls in opposite directions:
+
+- The duck-typed signal compatibility check honors prototype-inherited `aborted` / `addEventListener` (T-API-64n / T-API-64n2 already pin this), suggesting ordinary property access is the convention.
+- SPEC §9.5's own-enumerable-only rule for `env` is *explicit*, suggesting the outer options would have been similarly explicit if the same restriction applied.
+
+But the SPEC does not state which rule applies for the outer options' fields, and TEST-SPEC has no direct coverage of prototype-inherited `cwd` / `envFile` / `maxIterations` / `env` / `signal` on the outer options object.
+
+**Impact on TEST-SPEC.** No tests can be added for the inherited-field semantics on the outer options without picking an interpretation. T-API-61i / T-API-61k cover null-prototype and class-instance options *with own properties*; T-API-61l covers `Map` (no recognized field names appear as own properties). None test inherited fields on the outer options.
+
+**Resolution requested.** Amend SPEC §9.5 (or the §9.1 / §9.2 option-snapshot-timing paragraphs) to state explicitly whether the outer `options` object's recognized fields are read via:
+
+1. Ordinary JS property access (honoring inherited fields), matching the duck-typed signal precedent, or
+2. Own-enumerable-only access, matching the inner `options.env` rule.
+
+Either resolution unblocks adding the corresponding test coverage (inherited `maxIterations` / `cwd` / `envFile` / `signal` / `env` honored or ignored).
diff --git a/SPEC.md b/SPEC.md
index 517af3d..15a62a2 100644
--- a/SPEC.md
+++ b/SPEC.md
@@ -78,14 +78,14 @@ Each workflow has a **default entry point**: a script named `index` (i.e., `inde
 
 A workflow may include a `package.json` that serves two optional purposes:
 
-1. **Dependency management:** The workflow can declare its own dependencies. Users manage installation themselves (`npm install` / `bun install` within the workflow directory). loopx does not auto-install dependencies. If `node_modules/` is missing and the script fails to import a package, the resulting error is the active runtime's normal module resolution error.
+1. **Dependency management:** The workflow can declare its own dependencies. `loopx install` auto-runs `npm install` in each committed workflow that contains a top-level `package.json` (see section 10.10), so a workflow's `node_modules/` is normally populated by the time `loopx run` first spawns one of its scripts. The presence of a top-level `package.json` is the sole trigger — whether it declares any dependencies is not inspected. The `--no-install` flag on `loopx install` suppresses the install-time step for users who prefer manual control or a non-npm package manager. At runtime, loopx does **not** re-install dependencies — `loopx run` does not invoke `npm install` on a missing `node_modules/`. If `node_modules/` is missing and a script fails to import a package, the resulting error is the active runtime's normal module resolution error.
 2. **Version declaration:** The workflow can declare a `loopx` version requirement (see section 3.2).
 
 The `main` field is no longer used to determine the entry point. The entry point is always the `index` script by convention. If a `package.json` contains a `main` field, it is ignored by loopx.
 
 The `type` field (`"module"`) continues to be relevant for Node.js module resolution within the workflow.
 
-**Failure modes:** If a workflow's `package.json` is absent, unreadable, contains invalid JSON, or declares an invalid semver range for `loopx`, see section 3.2 for the defined behavior. In all cases, a broken `package.json` degrades version checking but does not prevent the workflow from being used or installed.
+**Failure modes:** If a workflow's `package.json` is absent, unreadable, contains invalid JSON, or declares an invalid semver range for `loopx`, see section 3.2 for the defined behavior. A broken `package.json` degrades version checking but does not prevent the workflow from being used or installed; an unreadable `package.json`, invalid JSON, or an invalid `loopx` semver range also causes `loopx install`'s auto-install step to skip that workflow (section 10.10).
 
 ### 2.2 Loop
 
@@ -190,7 +190,14 @@ A local install provides two guarantees:
 
 #### Project root
 
-For loopx, the **project root** is always the invocation cwd. This is the same directory where `.loopx/` lives (when it exists), but the project root is determined by cwd alone — it does not depend on `.loopx/` existing. This means delegation, version pinning, and all project-root-relative behavior work regardless of whether `.loopx/` has been initialized.
+For loopx, the **project root** depends on the invocation path: under the CLI it is `process.cwd()` at invocation, and under the programmatic API it is the resolved `RunOptions.cwd` when supplied, otherwise `process.cwd()` at call time. This is the same directory where `.loopx/` lives (when it exists), but the project root is determined by those rules alone — it does not depend on `.loopx/` existing. This means delegation, version pinning, and all project-root-relative behavior work regardless of whether `.loopx/` has been initialized.
+
+**Project-root resolution.** Two paths set the project root:
+
+- **CLI:** `LOOPX_PROJECT_ROOT` is exactly the string returned by loopx's own `process.cwd()` at invocation. loopx does not consult `$PWD` and does not apply `realpath` / canonicalization beyond what the runtime already provides. On POSIX systems where `getcwd(3)` canonicalizes, a CLI invocation from a symlinked directory yields a canonical `LOOPX_PROJECT_ROOT`.
+- **Programmatic:** `LOOPX_PROJECT_ROOT` is `RunOptions.cwd` if supplied, otherwise `process.cwd()` at call time. A relative `RunOptions.cwd` is resolved via `path.resolve(process.cwd(), options.cwd)` once at call time; an absolute value is used unchanged. `path.resolve` is a pure string operation — symlinked components in `RunOptions.cwd` are preserved verbatim. No further `realpath` is applied; callers who need a canonical realpath compute one themselves.
+
+The project root is also the script execution cwd for every spawned script (see section 6.1) and the root beneath which `.loopx/` workflow discovery runs; the discovery-time workflow paths cached during that step are what loopx later injects as `LOOPX_WORKFLOW_DIR` (see section 6.1 and section 8). The injected `LOOPX_WORKFLOW_DIR` is read from those cached paths, not recomposed from project-root pieces. For `RunOptions.cwd` type and validation rules, see section 9.5.
 
 #### Resolution order (highest precedence first)
 
@@ -260,7 +267,11 @@ Scripts spawned by loopx need access to the `output` and `input` helpers via `im
 
 **For Bun:** Bun's module resolver supports `NODE_PATH` for both CJS and ESM. loopx sets `NODE_PATH` to include its own package directory when running under Bun.
 
-In both cases, the resolution **points to the post-delegation version** when no closer `node_modules/loopx` exists. If a local install triggered delegation, the helpers resolve to the local version's package. However, if a workflow has its own `node_modules/loopx`, standard module resolution applies and the closer package takes precedence over the CLI-provided one. This is a natural consequence of running scripts with the workflow directory as cwd (section 6.1).
+**Resolution precedence.** Standard file-relative resolution of `"loopx"` from the importing module's path always wins; the CLI-provided fallback applies only when no `node_modules/loopx` is found by standard resolution. This precedence is independent of cwd — Node ESM, tsx, and Bun resolve bare specifiers and relative imports from the importing module's file path, not from `process.cwd()`. The custom Node/tsx resolve hook installed via `module.register()` must preserve standard precedence: it must first attempt standard file-relative resolution (via `defaultResolve` delegation or an equivalent file-path walk-up) and fall back to the CLI package exports only when standard resolution finds no `node_modules/loopx`.
+
+In practice, when no closer `node_modules/loopx` exists, resolution **points to the post-delegation version** — if a local install triggered delegation, the helpers resolve to the local version's package; otherwise they resolve to the global install. When standard resolution sees a closer `node_modules/loopx`, it wins and the CLI fallback does not run; however, under symlinked JS/TS entry paths, Node's main-module realpath behavior may prevent a workflow-local `node_modules/loopx` on the logical path from being seen (see the symlink caveat below).
+
+**Symlink caveat for JS/TS entry paths.** Node's default main-module handling applies `realpath` to the main module's file path. When the absolute discovery-time entry path traverses any symlink (workflow directory entry, entry script file, or intermediate ancestor), the resolver walks up from the canonical target rather than the symlink-preserving spelling, so workflow-local `node_modules/loopx` on the logical path is not guaranteed to win even with a correctly delegating hook.
 
 loopx does **not** override standard module resolution to force the CLI version. This means a workflow with a locally installed `loopx` may get different helper behavior than the running CLI provides. The workflow's `package.json` version declaration (section 3.2) serves as the intended mechanism for surfacing version mismatches. No warning is emitted for this scenario in v1.
 
@@ -291,7 +302,9 @@ Scripts are executed exclusively via the `run` subcommand. `run` accepts exactly
 - `loopx run ralph:check-ready` runs the `check-ready` script in the `ralph` workflow.
 - `loopx run ralph:index` explicitly runs the `index` script (same as bare `loopx run ralph`).
 - The target is required. `loopx run` with no target (e.g., `loopx run` or `loopx run -n 5`) is a usage error (exit code 1). This does not inspect `.loopx/` or perform discovery.
-- More than one positional argument (e.g., `loopx run ralph bar`) is a usage error (exit code 1).
+- More than one positional argument (e.g., `loopx run ralph bar`) is a usage error (exit code 1). A `name=value` token in a second positional position is rejected on the same "more than one positional" rule — `loopx run ralph adr=0003` is a usage error, not a named-argument syntax.
+- A sole positional `name=value` (e.g., `loopx run adr=0003`) is parsed as a target string. The string contains `=`, which is not in the `[a-zA-Z0-9_][a-zA-Z0-9_-]*` pattern, so target-syntax validation rejects it. The surfaced CLI failure still follows the normal pre-iteration ordering in section 7.1 — for example, `.loopx/` discovery may fail first if the directory is missing, in which case the discovery error is what the user sees.
+- `--` is **not** an end-of-options marker for `run`. Outside the `-h` / `--help` short-circuit, `--` in any position is rejected as an unrecognized flag / usage error under the existing rejection rules. The sole CLI surface for per-run values is the shell env prefix (`key=value loopx run <target>`), which flows through inherited `process.env` at the section 8.3 inherited-env tier.
 - If the workflow does not exist in `.loopx/`, loopx exits with an error. If the workflow exists but the specified script does not, loopx exits with an error.
 - If a workflow has no `index` script and is invoked without specifying a script (e.g., `loopx run ralph`), loopx exits with an error (exit code 1). The workflow is still valid — its scripts can be targeted explicitly.
 - `loopx` with no arguments shows top-level help (equivalent to `loopx -h`). No discovery is performed.
@@ -314,7 +327,7 @@ The following target strings are invalid in all contexts — CLI invocation (`lo
 
 Existing structured-output parsing semantics are unchanged: if `goto` is present but not a string, it is treated as absent. Target validation applies only after a `goto` value has been parsed as a string.
 
-For CLI invocation and the programmatic API, invalid targets are rejected at the same point as a missing workflow (after discovery, or lazily on first iteration for the API). For `goto` values, invalid targets produce an error at transition time (exit code 1).
+For the CLI, invalid targets are rejected at the same point as a missing workflow (after discovery), under the pre-iteration ordering in section 7.1. For the programmatic API, invalid targets surface lazily on first iteration (`run()`) or promise rejection (`runPromise()`), on the pre-iteration error path; relative ordering against other pre-iteration failures is implementation-defined except for the pinned option-error and abort-precedence rules in section 9.3. For `goto` values, invalid targets produce an error at transition time (exit code 1).
 
 ### 4.2 Options
 
@@ -351,6 +364,8 @@ Within `run`, options and the target may appear in any order.
 - Target requirements are suppressed (zero or multiple positionals are not errors).
 - `-n` and `-e` values are not parsed or validated (including duplicates and invalid values).
 - Unknown flags are ignored.
+- `--` in any position is ignored (not rejected as the unrecognized flag it would otherwise be under section 4.1).
+- `name=value` positional tokens in any position are ignored (not rejected as extra positionals or as invalid target strings).
 - Examples:
   - `loopx run -h ralph` — shows run help (target ignored).
   - `loopx run ralph -h` — shows run help (`-h` after target still triggers help short-circuit).
@@ -360,6 +375,8 @@ Within `run`, options and the target may appear in any order.
   - `loopx run -h -n 5 -n 10` — shows run help (duplicate `-n` not rejected).
   - `loopx run -h foo bar` — shows run help (extra positional not rejected).
   - `loopx run -h --unknown` — shows run help (unknown flag not rejected).
+  - `loopx run -h -- ralph` — shows run help (`--` not rejected).
+  - `loopx run -h ralph adr=0003` — shows run help (`name=value` token not rejected).
 
 #### `install`-scoped options
 
@@ -367,13 +384,14 @@ Within `run`, options and the target may appear in any order.
 |------|-------------|
 | `-w <name>`, `--workflow <name>` | Install only the named workflow from a multi-workflow source (see section 10.8). |
 | `-y` | Override version mismatch and workflow collision checks (see sections 10.5 and 10.6). |
+| `--no-install` | Suppress auto-install of workflow dependencies (see section 10.10). When present, `loopx install` commits workflow files but does not run `npm install` and does not synthesize the `.gitignore` safeguard for any selected workflow. No short form. |
 | `-h`, `--help` | Print install help and exit. |
 
-**Duplicate flags:** Repeating `-w` or `-y` is a usage error (exit code 1) — unless `-h` / `--help` is present.
+**Duplicate flags:** Repeating `-w`, `-y`, or `--no-install` is a usage error (exit code 1) — unless `-h` / `--help` is present.
 
 **Unrecognized flags:** Unrecognized flags (e.g., `loopx install --unknown <source>`) are usage errors (exit code 1) — unless `-h` / `--help` is present.
 
-**`install -h` / `--help` short-circuit:** When `-h` / `--help` is present, loopx shows install help, exits 0, and ignores all other install-level arguments unconditionally. Source is not required, flags are not validated, and no network requests are made.
+**`install -h` / `--help` short-circuit:** When `-h` / `--help` is present, loopx shows install help, exits 0, and ignores all other install-level arguments unconditionally. Source is not required, flags are not validated (including duplicate or extraneous `--no-install`), and no network requests are made.
 
 ### 4.3 Subcommands
 
@@ -469,13 +487,13 @@ Legacy layouts are not recognized: loose script files placed directly in `.loopx
 - Subdirectories within a workflow are ignored.
 - Name collisions (e.g., `check.sh` and `check.ts` in the same workflow) follow the rules in section 5.2.
 
-**Symlink policy:** Symlinks within `.loopx/` are followed during discovery. A symlinked workflow directory or script file is treated identically to its non-symlinked equivalent. Symlink resolution does not affect workflow or script naming — names are derived from the symlink's own name, not its target.
+**Symlink policy:** Symlinks within `.loopx/` are followed during discovery to determine entry types — a symlinked `.loopx` directory, a symlinked `.loopx/<workflow>` directory, and a symlinked entry script file are all treated identically to their non-symlinked equivalents for purposes of "is this a workflow / script?". The discovered path spelling is preserved (no `realpath` / canonicalization is applied), and that preserved spelling is what loopx caches for spawn-time invocation, `LOOPX_WORKFLOW_DIR` injection (section 6.1), and Bash `$0` derivation (section 6.2). Symlink resolution does not affect workflow or script naming — names are derived from the symlink's own name, not its target.
 
 **Discovery metadata is cached at loop start for the duration of the loop.** This means:
 
 - Workflows and scripts added, removed, or renamed during loop execution are not detected until the next invocation.
 - **Edits to the contents of an already-discovered script file take effect on subsequent iterations**, because the child process reads the file from disk each time it is spawned.
-- **If a discovered script's underlying file is removed or renamed mid-loop**, execution uses the cached entry path and fails at spawn time as a normal child-process launch error. This is treated as a non-zero exit (section 7.2).
+- **If a discovered script's underlying file is removed or renamed mid-loop**, execution uses the cached entry path and fails at spawn time. This is a child launch / spawn failure under section 7.2 (not a non-zero exit, since the child never starts running user code).
 
 Discovery runs at loop start for `loopx run <target>` and during `loopx run -h`. Discovery does **not** run for top-level help (`loopx -h` / `loopx --help` / bare `loopx`).
 
@@ -522,14 +540,35 @@ Not all commands require `.loopx/` to exist or be valid:
 
 ### 6.1 Working Directory
 
-All scripts run with the **workflow directory** as their working directory (e.g., `.loopx/ralph/`). This ensures relative imports and `node_modules/` resolve naturally.
+All scripts run with **`LOOPX_PROJECT_ROOT` as their working directory** (see section 3.2). This applies to every script in the run — starting target, intra- and cross-workflow `goto` destinations, and loop resets all spawn at the same project-root cwd. Scripts remain free to `cd` (Bash) or `process.chdir()` (JS/TS) within the child process; such changes are scoped to that child and do not affect later spawns, which always start at project-root cwd.
+
+**Invocation path.** loopx invokes each script using its **absolute discovery-time path** (e.g., `bash /project/.loopx/review-adr/index.sh`). loopx does not canonicalize that path; the spelling preserved at discovery time (per section 5.1's symlink policy) is the spelling used at spawn time and is the basis for `LOOPX_WORKFLOW_DIR` (see below).
+
+**`LOOPX_PROJECT_ROOT` injection.** loopx injects `LOOPX_PROJECT_ROOT` into every script's environment, set to the absolute path of the project root (see section 3.2; for the programmatic API, this is `RunOptions.cwd` if provided — see section 9.5). Because cwd is already the project root, the variable is redundant for project-root-relative reads in the child's own working directory, but it remains injected for scripts that `cd` elsewhere or hand paths to tools that don't inherit cwd.
+
+**`LOOPX_WORKFLOW_DIR` injection.** loopx injects `LOOPX_WORKFLOW_DIR` into every script's environment, set to the absolute path of the workflow directory containing the currently-spawned script — specifically, the directory portion of the cached absolute discovery-time script path. In the v1 layout this normally corresponds to `"$LOOPX_PROJECT_ROOT/.loopx/$LOOPX_WORKFLOW"`, but the injected form is derived from the cached discovery path rather than recomposed from those components, so it remains consistent with the spawn path under trailing-slash variations, symlinked `.loopx/<workflow>` entries, and any lexical normalization the implementation applies during discovery. The injected form is authoritative — scripts should prefer it over re-deriving the path.
+
+`LOOPX_WORKFLOW_DIR` tracks the currently-spawned script's containing workflow and refreshes per-spawn alongside `LOOPX_WORKFLOW`: starting-target spawn, intra-workflow `goto`, cross-workflow `goto` (A → B sets `LOOPX_WORKFLOW_DIR` to B's directory before the B-side spawn; deeper chains A → B → C each observe their own workflow's directory), and loop reset. Within a single script execution the value is stable — a top-level workflow script and a sibling helper it sources or imports both read the same `LOOPX_WORKFLOW_DIR` because the env var is injected once per child spawn and inherited by the whole process.
+
+**Symlink behavior.** `LOOPX_WORKFLOW_DIR` is derived from the discovery-time path, not via `realpath`. A symlinked `.loopx/<workflow>` directory entry, a symlinked `.loopx` directory, a symlinked entry script file, or a symlinked project-root ancestor (via `RunOptions.cwd`) all preserve their discovered spelling in `LOOPX_WORKFLOW_DIR`.
+
+**Directory identity vs. string spelling.** loopx controls the child's *effective* working directory by spawning with `LOOPX_PROJECT_ROOT` as cwd (same device/inode as `LOOPX_PROJECT_ROOT`) but does not control the *string spelling* that runtime cwd APIs report. The `LOOPX_PROJECT_ROOT` spelling itself depends on how the project root was supplied (section 3.2):
 
-loopx injects `LOOPX_PROJECT_ROOT` into every script's environment, set to the absolute path of the project root (see section 3.2; for the programmatic API, this is `RunOptions.cwd` if provided — see section 9.5). This is essential for scripts that need to reference project files outside their workflow directory.
+- **CLI:** `LOOPX_PROJECT_ROOT` is exactly the string returned by loopx's own `process.cwd()` at invocation. On POSIX systems where `getcwd(3)` canonicalizes, this is already a canonical path, and `LOOPX_PROJECT_ROOT` does **not** preserve a symlinked spelling under the CLI.
+- **Programmatic:** `LOOPX_PROJECT_ROOT` is `RunOptions.cwd` (resolved lexically via `path.resolve` with no `realpath`) or `process.cwd()` at call time. A symlink-preserving spelling supplied via `RunOptions.cwd` is preserved verbatim in `LOOPX_PROJECT_ROOT`; the `process.cwd()` fallback follows the same canonicalization characteristics as the CLI case.
+
+In either regime the child's effective cwd has the same device/inode as `LOOPX_PROJECT_ROOT`, but the *string spelling* that runtime cwd APIs report inside the child (e.g., Node/Bun's `process.cwd()`, which typically canonicalizes via `getcwd(3)`) is produced by the runtime and may differ from the spelling loopx used at spawn. Bash `$PWD` and bare `pwd` are shell-maintained and inherit loopx's own `PWD`, so byte-for-byte equality between Bash `$PWD` / bare `pwd` and `LOOPX_PROJECT_ROOT` is not a loopx guarantee in any regime. Scripts that need the loopx-chosen spelling read `LOOPX_PROJECT_ROOT`; scripts that need the kernel cwd spelling use `process.cwd()` (JS/TS) or `pwd -P` / `/bin/pwd` (Bash); scripts that need filesystem identity use `stat(".")`.
+
+**`PWD` is not a protocol variable.** loopx neither sets nor unsets `PWD` in the child environment; whatever value loopx's own process holds is inherited unchanged. A caller who wants a specific `PWD` in the child passes it via `RunOptions.env` (section 9.5) or inherited env, subject to Bash's standard POSIX inheritance behavior. `PWD` is outside the section 8.3 protocol-variable tier and outside the section 13 reserved list.
+
+**Cross-workflow rendezvous.** Scripts handing data across a cross-workflow `goto` use `$LOOPX_TMPDIR` (preferred — see section 7.4) or a shared fixed location like `$LOOPX_PROJECT_ROOT/.loopx/shared/…`. `LOOPX_WORKFLOW_DIR` always points at the currently-spawned script's own workflow and is not a rendezvous point.
 
 ### 6.2 Bash Scripts
 
 Bash scripts (`.sh`) are executed as child processes via `/bin/bash`. The script's stdout is captured as its structured output. Stderr is passed through to the user's terminal.
 
+Because loopx invokes each script using its absolute discovery-time path (section 6.1), Bash `$0` is the absolute discovery-time path of the entry script. Bash does not canonicalize `$0`, so `$(dirname "$0")` equals `LOOPX_WORKFLOW_DIR` byte-for-byte regardless of whether symlinks appear anywhere in the entry path (workflow directory entry, entry script file, or intermediate component). This Bash equality is normative.
+
 ### 6.3 JS/TS Scripts
 
 JavaScript and TypeScript scripts are executed as child processes using `tsx`, which handles `.js`, `.jsx`, `.ts`, and `.tsx` files uniformly. `tsx` is a dependency of loopx and does not need to be installed separately by the user.
@@ -541,6 +580,8 @@ JavaScript and TypeScript scripts are executed as child processes using `tsx`, w
 
 When running under Bun, loopx uses Bun's native TypeScript/JSX support instead of `tsx`.
 
+Because loopx invokes each script using its absolute discovery-time path (section 6.1), `dirname(fileURLToPath(import.meta.url))` equals `LOOPX_WORKFLOW_DIR` only when the absolute entry path is symlink-free in every component. Node applies `realpath` to the main module's file path by default, and Bun's behavior is not specified to match; loopx does not pass runtime-specific symlink-preservation flags. `LOOPX_WORKFLOW_DIR` is authoritative for JS/TS code that needs the discovery-time workflow path.
+
 ### 6.4 `output()` Function (JS/TS)
 
 When imported from `loopx`, the `output()` function writes structured JSON to stdout and terminates the process.
@@ -598,24 +639,25 @@ The first script invocation in a loop receives **no input**. Stdin is empty.
 1. A target is required. If none was provided, this is a usage error (exit code 1) — see section 4.1. Discover workflows and scripts in the `.loopx/` directory per section 5.1. Validate for name collisions (section 5.2) and name restrictions (section 5.3) across **all** discovered workflows — these are fatal in run mode. Cache the discovery results.
 2. Load environment variables (global + local via `-e`). Cache the resolved set for the duration of the loop.
 3. Resolve the starting target from the target provided to `loopx run`. Parse the workflow and optional script portions. If the workflow does not exist in the cached discovery results, exit with an error. If a script was specified and does not exist in the workflow, exit with an error. If no script was specified, resolve to `index` — if the workflow has no `index` script, exit with an error.
-4. If `-n 0` was specified: exit with code 0 (no iterations executed, no workflow-level version checking).
+4. If `-n 0` was specified: exit with code 0 (no iterations executed, no workflow-level version checking, no `LOOPX_TMPDIR` created).
 5. Check the starting workflow's version declaration (section 3.2) against the running loopx version on first entry.
-6. Execute the starting target with no input (first iteration).
-7. Capture stdout. Parse it as structured output per section 2.3.
-8. Increment the iteration counter.
-9. If `stop` is `true`: exit with code 0.
-10. If `-n` was specified and the iteration count has been reached: exit with code 0. The output from this final iteration is still yielded/observed before termination.
-11. If `goto` is present:
+6. Create the run-scoped temporary directory `LOOPX_TMPDIR` per section 7.4. This step runs after the starting workflow's version check (step 5) and immediately before the first child spawn. Pre-spawn failures, `-n 0` / `maxIterations: 0` early exits, and aborts observed before this step do not create a tmpdir.
+7. Execute the starting target with no input (first iteration).
+8. Capture stdout. Parse it as structured output per section 2.3.
+9. Increment the iteration counter.
+10. If `stop` is `true`: exit with code 0.
+11. If `-n` was specified and the iteration count has been reached: exit with code 0. The output from this final iteration is still yielded/observed before termination.
+12. If `goto` is present:
     a. Validate the `goto` value against the target validation rules (section 4.1). If invalid, print an error and exit with code 1.
     b. Resolve the target: a bare name targets a script in the current workflow; a qualified `workflow:script` targets a specific workflow and script.
     c. Validate that the resolved workflow exists in the cached discovery results. If not found, print an error and exit with code 1.
     d. Validate that the resolved script exists in the target workflow. If not found, print an error and exit with code 1.
     e. If entering a workflow for the first time during this loop run, check its version declaration (section 3.2).
     f. Execute the resolved target with `result` piped via stdin (or empty stdin if `result` is absent).
-    g. Return to step 7 with the new script's output.
-12. If `goto` is absent:
+    g. Return to step 8 with the new script's output.
+13. If `goto` is absent:
     a. Re-run the **starting target** with no input.
-    b. Return to step 7.
+    b. Return to step 8.
 
 **Iteration counting:** `-n` / `maxIterations` counts **every target execution**, including goto hops — not just returns to the starting target. For example, if `ralph:index` outputs `goto: "check-ready"` and `ralph:check-ready` outputs `goto: "review-adr:start"`, that is three iterations.
 
@@ -623,10 +665,18 @@ The first script invocation in a loop receives **no input**. Stdin is empty.
 
 ### 7.2 Error Handling
 
-- **Non-zero exit code from a script:** The loop **stops immediately**. loopx exits with code 1. The script's stderr has already been passed through to the terminal. Any stdout produced by the script before it failed is not parsed as structured output.
+- **Non-zero exit code from a script:** The loop **stops immediately**. loopx exits with code 1. The script's stderr has already been passed through to the terminal. Any stdout produced by the script before it failed is not parsed as structured output. `LOOPX_TMPDIR` cleanup runs before exit per section 7.4.
 - **Missing workflow / missing script / missing default entry point:** If the starting target resolves to a workflow that does not exist, a script that does not exist in that workflow, or a bare workflow invocation where `index` is missing, loopx exits with code 1 and prints an error to stderr. These checks occur during target resolution (step 3 in section 7.1) before any iterations run.
-- **Invalid `goto` target:** If `goto` contains an invalid target string (section 4.1), references a workflow that does not exist in the cached discovery results, or references a script that does not exist within the target workflow, loopx prints an error message to stderr and exits with code 1.
+- **Invalid `goto` target:** If `goto` contains an invalid target string (section 4.1), references a workflow that does not exist in the cached discovery results, or references a script that does not exist within the target workflow, loopx prints an error message to stderr and exits with code 1. `LOOPX_TMPDIR` cleanup runs before exit.
 - **Missing `.loopx/` directory:** When executing via `loopx run <target>`, if `.loopx/` does not exist, loopx exits with an error instructing the user to create it.
+- **`LOOPX_TMPDIR` creation failure:** If any step of the tmpdir creation sequence (per section 7.4) fails, loopx does not spawn any child; the CLI exits with code 1, `run()` throws on first iteration, and `runPromise()` rejects. Best-effort cleanup runs on any partial directory per section 7.4 without masking the original creation error.
+- **Child launch / spawn failure after tmpdir creation:** If a child cannot be launched after `LOOPX_TMPDIR` has been created — including a discovered script removed or renamed mid-loop per section 5.1, runtime rejection of a child environment entry from any env tier (most reliably an entry whose name or value contains an embedded NUL byte; the runtime does not distinguish tiers), `exec` failure, or any other pre-first-line-of-user-code spawn-path error — loopx exits with code 1 (CLI), throws (`run()`), or rejects (`runPromise()`). `LOOPX_TMPDIR` cleanup runs before exit.
+
+**Cleanup idempotence.** loopx performs at most one cleanup attempt per created `LOOPX_TMPDIR` over the lifetime of the run. Racing terminal triggers (SIGTERM during cleanup of a prior SIGINT; abort concurrent with consumer `.return()` / `.throw()`; non-zero exit concurrent with abort; abort after final yield concurrent with a consumer `.throw()`; child spawn failure concurrent with abort; abort concurrent with tmpdir creation failure; etc.) do not start a second cleanup attempt and do not re-emit cleanup warnings.
+
+**Terminal-outcome precedence.** The selection of which terminal outcome is surfaced is governed by explicit precedence rules elsewhere — the pre-first-`next()` consumer-cancellation carve-out (section 9.1), the abort-wins-over-pre-iteration-failures rule (section 9.3), the CLI pre-iteration signal-wins rule (section 7.3), and the abort-after-final-yield rule (section 9.3). Except where an explicit precedence rule applies, the first terminal trigger observed by loopx determines the surfaced outcome among genuinely racing triggers. "Observed by loopx" refers to the point at which the trigger enters loopx's own tracking (signal handler, abort listener, child-exit callback, consumer interaction) — not OS-level delivery order. Idempotence and warning cardinality are independent of which outcome surfaces.
+
+**Cleanup warning cardinality.** Every run emits at most one cleanup-related stderr warning. The exact warning text format is implementation-defined; cleanup warnings do not affect the CLI exit code, the generator outcome, or the promise rejection reason. Tmpdir location, mode, identity-fingerprint cleanup safety, symlink / non-directory / mismatched-directory / renamed-away handling, mount-point non-detection, and absence of stale-tmpdir reaping are specified in section 7.4.
 
 ### 7.3 Signal Handling
 
@@ -634,8 +684,71 @@ loopx handles process signals to ensure clean shutdown:
 
 - **SIGINT / SIGTERM:** The signal is forwarded to the **active child process group** (not just the direct child). This ensures grandchild processes (e.g., agent CLIs spawned by scripts) also receive the signal, preventing orphaned processes.
 - **Grace period:** After forwarding the signal, loopx waits **5 seconds** for the child process group to exit. If the process group has not exited after 5 seconds, loopx sends SIGKILL to the process group.
-- **Exit code:** After the child exits, loopx exits with code `128 + signal number` (standard POSIX convention, e.g., 130 for SIGINT).
-- **Between iterations:** If no child process is running (e.g., between iterations), loopx exits immediately with the appropriate signal exit code.
+- **Tmpdir cleanup before exit:** When `LOOPX_TMPDIR` has been created, cleanup runs after any active child process group has exited (per the grace period above, including SIGKILL escalation) and before loopx exits with the signal's code. When no child is active, cleanup runs immediately.
+- **Exit code:** After the child exits and any tmpdir cleanup completes, loopx exits with code `128 + signal number` (standard POSIX convention, e.g., 130 for SIGINT).
+- **Between iterations:** If no child process is running (e.g., between iterations), loopx exits immediately with the appropriate signal exit code (after `LOOPX_TMPDIR` cleanup).
+
+**Pre-iteration signal-wins precedence (CLI).** SIGINT / SIGTERM observed by loopx's installed pre-iteration signal handler wins over non-signal pre-iteration failures not yet surfaced at that point: loopx cleans up any partial tmpdir and exits with `128 + signal number` regardless of which non-signal pre-iteration step (target syntax validation, `.loopx/` discovery, env-file loading, target resolution, tmpdir creation) would otherwise have failed. The contract is phrased around handler observation, not OS-level delivery — loopx is not required to make pre-iteration async or poll for pending signals between steps.
+
+Signal-wins precedence begins only after the `run -h` / `--help` short-circuit and usage-level argument parsing have completed *and* loopx has installed its pre-iteration signal handlers. Signals delivered in the pre-handler-installation window (process startup, argument parsing, help short-circuit) are outside this precedence: either the runtime applies POSIX default signal disposition and terminates the process, or parsing completes and the parser-level usage error surfaces with exit code 1. Both outcomes are conforming.
+
+### 7.4 Run-scoped Temporary Directory (`LOOPX_TMPDIR`)
+
+For each `loopx run` (CLI) or `run()` / `runPromise()` (programmatic) invocation that reaches execution, loopx creates a unique temporary directory before the first child process spawns and injects its absolute path into every script's environment as `LOOPX_TMPDIR` (see section 8). Scripts use this directory for intra-run scratch state.
+
+**Parent selection.** The tmpdir parent is `os.tmpdir()` evaluated in loopx's own process environment. The parent is captured on the same schedule as the inherited `process.env` snapshot (section 8): synchronously at the `runPromise()` call site for `runPromise()`; at the first `next()` call for `run()`; pre-iteration for the CLI. `TMPDIR` / `TEMP` / `TMP` entries in env files or `RunOptions.env` reach spawned scripts but do not mutate loopx's own `process.env` and therefore do not redirect the tmpdir parent. Because the parent is captured on the inherited-env schedule, a synchronous `process.env.TMPDIR = …` mutation after `runPromise()` returns does not affect the tmpdir parent for that run, while a mutation between `run()` returning and first `next()` **does**. Callers who need a deterministic parent for `runPromise()` set `TMPDIR` in loopx's inherited environment before the call.
+
+**Location, naming, and mode.** The directory is created under the selected parent via `mkdtemp` with a `loopx-` prefix, mode `0700`. The exact name format beyond the prefix is implementation-defined.
+
+**Creation order.** loopx performs the following steps in this exact order before any child is exposed to the path:
+
+1. `mkdtemp` to create the directory.
+2. Capture an identity fingerprint (e.g., device/inode pair) of the created directory.
+3. Verify or secure mode `0700`.
+
+This order is normative because it determines which cleanup-safety guarantee applies if a step fails:
+
+- **`mkdtemp` itself fails:** no path exists, so no cleanup is needed.
+- **Identity capture fails (after `mkdtemp` succeeded):** loopx attempts a single non-recursive `rmdir` on the path. This succeeds on an empty directory (the expected state immediately after `mkdtemp`) and fails without side effects on a symlink, non-directory, or non-empty directory. Without a recorded identity fingerprint, this remains outside the race-resistant guarantee: a same-user process that swapped the original `mkdtemp` directory for a different empty directory before the `rmdir` would have that replacement removed. loopx accepts this narrow trade-off as the cost of cleaning up the common identity-capture-failure case. If `rmdir` fails, loopx emits a single stderr warning and leaves the path in place.
+- **Mode-securing fails (after `mkdtemp` and identity capture succeeded):** loopx runs the full identity-fingerprint cleanup-safety routine described below.
+
+Cleanup failure during creation-failure handling emits at most one warning but does not mask the original creation error. If a SIGINT / SIGTERM or `AbortSignal` abort arrives concurrently with a creation failure, the signal / abort wins and any partial directory is cleaned up under the same rules.
+
+**Scope and lifecycle.**
+
+- **Created:** once per run, after the pre-iteration sequence (discovery, env-file loading, target resolution, version check) and immediately before the first child spawns. Pre-spawn failures, `-n 0` / `maxIterations: 0` early exits, and aborts observed before tmpdir creation do not create a tmpdir.
+- **Shared across iterations.** All scripts — starting target, intra- and cross-workflow `goto` destinations, loop resets — observe the same `LOOPX_TMPDIR` value.
+- **Persisted within the run.** Files written by one script remain visible to later scripts.
+- **Concurrent runs are isolated.** Each run receives its own distinct directory.
+
+**Cleanup triggers.** loopx runs cleanup on every terminal outcome of a run that reached tmpdir creation:
+
+- Normal completion (`stop: true` from a script, or `-n` / `maxIterations` reached).
+- Non-zero script exit; invalid `goto` target; missing workflow or script during `goto` resolution.
+- Child launch / spawn failure after tmpdir creation (per section 7.2).
+- SIGINT / SIGTERM to loopx — after any active child process group has exited (per section 7.3, including SIGKILL escalation), before loopx exits with the signal's code. If no child is active, cleanup runs immediately.
+- Programmatic `AbortSignal` abort — after any active child process group exits per section 9.1, before the generator throws or the promise rejects.
+- Consumer-driven cancellation under `run()` (`break` from `for await`, `.return()` / `.throw()` after first `next()`) — after terminating any active child per section 9.1, before the generator settles.
+
+For `run()`, cleanup on normal completion is guaranteed only once the generator is driven to settlement (`{ done: true }`, `.return()`, `.throw()`, or a `for await` loop that runs to completion). The final yielded `Output` is not itself settlement; a caller that consumes the final output and abandons the generator may leak the tmpdir.
+
+Cleanup does **not** run when loopx itself is killed via SIGKILL or the host crashes; leaked tmpdirs are expected to be reaped by OS temp-cleaning policy. **loopx does not reap stale tmpdirs at startup.**
+
+**Identity-fingerprint cleanup safety.** Cleanup is path-based and best-effort — not a sandbox against actively racing same-user processes. At cleanup time, loopx `lstat`s the `LOOPX_TMPDIR` path and dispatches on the outcome:
+
+1. **Path no longer exists (ENOENT):** no-op.
+2. **Path is a symlink:** unlink the symlink entry; do not follow the target.
+3. **Path is a regular file, FIFO, socket, or other non-directory non-symlink:** leave in place with a stderr warning. Unlinking would risk mutating unrelated data (hard-link `nlink` decrement, or data renamed into the path with `nlink == 1`).
+4. **Path is a directory whose identity matches the recorded identity:** recursively remove. Symlink entries encountered during the walk are unlinked but not traversed, so symlinks pointing outside the tmpdir do not collateral-delete their targets.
+5. **Path is a directory whose identity does not match:** leave in place with a stderr warning. loopx does not recursively remove a directory it did not create.
+
+If the top-level `lstat` fails for any reason other than ENOENT, the `unlink` in case 2 fails, or the recursive removal in case 4 fails, loopx emits a single stderr warning and makes no further changes. Combined with the cleanup idempotence rule in section 7.2, every run emits at most one cleanup warning; the warning text format is implementation-defined and warnings do not affect the CLI exit code, the generator outcome, or the promise rejection reason.
+
+**Renamed-away tmpdir.** A script that removes or renames its tmpdir during the run defeats automatic cleanup of the moved directory; loopx does not chase renamed tmpdirs.
+
+**Mount points.** loopx does not detect or avoid mount points inside `$LOOPX_TMPDIR`; scripts that mount into `$LOOPX_TMPDIR` take responsibility for unmounting before cleanup.
+
+**Race-resistance scope.** A race-resistant guarantee against a same-user process actively mutating the path during cleanup (fd-relative `openat` / `unlinkat` with `AT_SYMLINK_NOFOLLOW`) is out of scope for v1. The path-based, identity-matched best-effort cleanup above is the v1 contract.
 
 ---
 
@@ -649,14 +762,14 @@ Global environment variables are stored in the loopx configuration directory at:
 $XDG_CONFIG_HOME/loopx/env
 ```
 
-If `XDG_CONFIG_HOME` is not set, it defaults to `~/.config`, resulting in `~/.config/loopx/env`.
+If `XDG_CONFIG_HOME` is not set, the fallback is `$HOME/.config`, resulting in `$HOME/.config/loopx/env`. `HOME` is read from the inherited environment on the same schedule as `XDG_CONFIG_HOME` (see the snapshot-timing paragraph below).
 
 The file uses `.env` format with the following rules:
 
 - One `KEY=VALUE` pair per line.
 - **No whitespace is permitted around `=`.** The key extends to the first `=`, and the value is everything after it to the end of the line (trimmed of trailing whitespace).
 - Lines starting with `#` are comments. **Inline comments are not supported** — a `#` after a value is part of the value.
-- Blank lines are ignored.
+- Blank lines are ignored. A line containing only whitespace (for example, spaces and/or tabs, after removing the line terminator) is considered blank and is ignored silently without a warning.
 - Duplicate keys: **last occurrence wins**.
 - Values are single-line strings. Values may be optionally wrapped in double quotes (`"`) or single quotes (`'`), which are stripped. "Wrapped" means the value begins and ends with the same quote character — if quotes are unmatched (e.g., `KEY="hello` or `KEY='world`), the value is treated literally with no quotes stripped. **No escape sequence interpretation** — content inside quotes is treated literally (e.g., `"\n"` is a backslash followed by `n`, not a newline).
 - No multiline value support.
@@ -666,11 +779,11 @@ If the directory or file does not exist, loopx treats it as having no global var
 
 **Concurrent mutation:** Concurrent writes to the same global env file (e.g., multiple simultaneous `loopx env set` calls) are not guaranteed to be atomic in v1. The result is undefined.
 
-**Environment variables are loaded once at loop start and cached for the duration of the loop.** Changes to env files during loop execution are not picked up until the next invocation.
+**Environment variables are loaded once at loop start and cached for the duration of the loop.** Changes to env files during loop execution are not picked up until the next invocation. The same once-per-run rule extends to the inherited `process.env`: loopx snapshots the caller's `process.env` once per run and reuses the snapshot for every child spawn in the run; mutations to `process.env` between spawns do not propagate. **Snapshot timing.** For the CLI, the inherited `process.env` snapshot is taken during the pre-iteration sequence at loop start (section 7.1, before the first child spawn). For the programmatic API, the snapshot is lazy under `run()` (captured at first `next()`) and eager under `runPromise()` (captured synchronously at the call site) — see sections 9.1 and 9.2 for the precise contracts. The tmpdir parent (the `TMPDIR` / `TEMP` / `TMP` values that `os.tmpdir()` reads in loopx's own process) is captured on the same schedule as the inherited-env snapshot — see section 7.4. Global env file path resolution (`$XDG_CONFIG_HOME/loopx/env`, with the documented `HOME`-based fallback) reads `XDG_CONFIG_HOME` / `HOME` from the inherited environment on the same schedule. `RunOptions.env` does **not** affect global env-file path resolution — `env` merges into the child environment after env-file loading (section 8.3), so an `XDG_CONFIG_HOME` or `HOME` entry supplied via `RunOptions.env` reaches spawned scripts but does not redirect where loopx looks for the global env file.
 
 ### 8.2 Local Override (`-e`)
 
-When `-e <path>` is specified during execution (`loopx run <target>` or the programmatic API), the file at `<path>` is read using the same `.env` format rules. If the file does not exist, loopx exits with an error.
+When a local env file is specified during execution — via `-e <path>` on the CLI or `RunOptions.envFile` in the programmatic API — the file is read using the same `.env` format rules. If the file does not exist, loopx exits with an error.
 
 **Note:** Under the `loopx run -h` short-circuit, `-e` is not parsed or validated — a missing env file is not an error in that context (see section 4.2).
 
@@ -680,18 +793,25 @@ Local variables are merged with global env vars. Local values take precedence on
 
 All resolved environment variables are injected into the script's execution environment alongside the inherited system environment, with the following precedence (highest wins):
 
-1. **loopx-injected variables** (`LOOPX_BIN`, `LOOPX_PROJECT_ROOT`, `LOOPX_WORKFLOW`) — always override any user-supplied values of the same name.
-2. **Local env file** (`-e`) values.
-3. **Global loopx env** (`$XDG_CONFIG_HOME/loopx/env`) values.
-4. **Inherited system environment.**
+1. **loopx-injected protocol variables** (`LOOPX_BIN`, `LOOPX_PROJECT_ROOT`, `LOOPX_WORKFLOW`, `LOOPX_WORKFLOW_DIR`, `LOOPX_TMPDIR`) — always override any user-supplied values of the same name.
+2. **`RunOptions.env`** (programmatic API only — see section 9.1 / 9.5).
+3. **Local env file** (`-e` / `RunOptions.envFile`) values.
+4. **Global loopx env** (`$XDG_CONFIG_HOME/loopx/env`) values.
+5. **Inherited system environment** (snapshotted once per run — see section 8.1).
+
+A `RunOptions.env` entry overrides same-named values from `-e`, the global env file, and inherited `process.env`, and is overridden by protocol variables. The CLI has no `RunOptions.env` surface; CLI callers pass per-run values via the shell env prefix (`key=value loopx run …`), which flows through inherited `process.env` at tier 5.
 
-loopx injects the following variables into every script execution:
+loopx injects the following protocol variables into every script execution:
 
 | Variable | Value |
 |----------|-------|
 | `LOOPX_BIN` | Resolved realpath of the effective loopx binary (post-delegation) |
 | `LOOPX_PROJECT_ROOT` | Absolute path to the project root (section 3.2) |
-| `LOOPX_WORKFLOW` | The name of the workflow containing the currently executing script |
+| `LOOPX_WORKFLOW` | The name of the workflow containing the currently-spawned script |
+| `LOOPX_WORKFLOW_DIR` | Absolute path of the workflow directory containing the currently-spawned script (section 6.1). Refreshed per-spawn alongside `LOOPX_WORKFLOW`. |
+| `LOOPX_TMPDIR` | Absolute path to the run-scoped temporary directory (section 7.4). Stable for the lifetime of the run. |
+
+**`PWD` is not a protocol variable.** loopx neither sets nor unsets `PWD`; the value loopx's own process holds is inherited unchanged. `PWD` is outside this protocol-variable tier and outside the section 13 reserved list. Callers wanting a specific `PWD` in the child supply it via `RunOptions.env` or inherited env, subject to Bash's standard POSIX inheritance behavior.
 
 **Note:** For Node.js/tsx, module resolution for `import from "loopx"` is handled via `--import` and a custom resolve hook (see section 3.3), not via `NODE_PATH`. For Bun, `NODE_PATH` is set internally but is not considered a user-facing injected variable.
 
@@ -726,7 +846,11 @@ run("ralph:check-ready")   // runs ralph:check-ready
 
 `target` is a required parameter. In TypeScript, omitting `target` is a static type error. In JavaScript, or when the type check is bypassed, runtime-invalid `target` values (e.g., `undefined`, `null`, `42`, or any non-string) are rejected lazily: `run()` still returns a generator without throwing, and the error is raised on first iteration (first `next()` call). For example, `run(undefined as any)` returns a generator that throws on first iteration.
 
-**Error timing:** `run()` snapshots its options and `cwd` at call time, but all errors (validation failures, missing workflows, missing scripts, discovery errors, invalid `target`) are surfaced lazily when iteration begins (i.e., on the first `next()` call or equivalent). The `run()` call itself always returns a generator without throwing.
+**Option-snapshot timing.** `run()` reads its `options` argument at the call site as a synchronous snapshot, but never throws at the call site. Each option field is read at most once per call, and a throwing getter or proxy trap is not re-invoked to retry. `options.signal` is read **before** other `RunOptions` fields, so an already-aborted signal is captured before any other option-field read can produce a snapshot exception. The order of the remaining option fields (`options.env`, `options.cwd`, `options.envFile`, `options.maxIterations`) is implementation-defined. Any exception raised during the snapshot — a throwing option-field getter, a `Proxy` `ownKeys` trap that throws while enumerating `options.env`, a throwing enumerable getter inside `options.env`, a throwing `Proxy` `get` trap on an included `options.env` key, or a throwing `options.env` getter on the options object itself — is captured and surfaced via the standard pre-iteration error path on the first `next()`, not at the call site.
+
+**Inherited-env and tmpdir-parent snapshot timing.** Under `run()`, the inherited `process.env` snapshot is **lazy** — captured on the first `next()` call alongside the rest of the pre-iteration sequence. Mutations to `process.env` between `run()` returning and first `next()` **are** observed; later mutations between iterations are not. The tmpdir parent (the `TMPDIR` / `TEMP` / `TMP` values that `os.tmpdir()` reads) is captured on the same schedule, so a mutation to `process.env.TMPDIR` between `run()` returning and first `next()` does affect the tmpdir parent for that run. Global env file path resolution (`XDG_CONFIG_HOME` / `HOME`) also uses this schedule. `LOOPX_TMPDIR` itself is created during the same pre-iteration sequence, between the starting workflow's version check and the first child spawn (section 7.1, step 6); cleanup runs before any error is surfaced (section 7.4 / 9.3).
+
+**Error timing.** All errors (validation failures, missing workflows, missing scripts, discovery errors, invalid `target`, invalid `options` fields including `options.env`, env-file loading failures, tmpdir-creation failures) are surfaced lazily when iteration begins (i.e., on the first `next()` call or equivalent). The `run()` call itself always returns a generator without throwing.
 
 Options can be passed as a second argument:
 
@@ -738,11 +862,13 @@ for await (const output of run("ralph", { maxIterations: 10, envFile: ".env" }))
 }
 ```
 
-**Early termination:** There are two cancellation mechanisms with different semantics:
+**Early termination.** There are two cancellation mechanisms with different semantics:
+
+- **Consumer-driven (`break`, `generator.return()`, `generator.throw()` after first `next()`):** loopx terminates the active child process group (if one is running — SIGTERM, then SIGKILL after 5 seconds) and ensures no further iterations start. If no child process is active at the time of cancellation (e.g., `break` after a yield, between iterations), the generator simply completes with no further yields. This is a silent, clean completion. `LOOPX_TMPDIR` cleanup runs before generator settlement.
 
-- **Consumer-driven (`break`, `generator.return()`):** loopx terminates the active child process group (if one is running — SIGTERM, then SIGKILL after 5 seconds) and ensures no further iterations start. If no child process is active at the time of cancellation (e.g., `break` after a yield, between iterations), the generator simply completes with no further yields. This is a silent, clean completion.
+- **AbortSignal:** When the `signal` is aborted, loopx terminates the active child process group (if one is running — SIGTERM, then SIGKILL after 5 seconds) and the generator **throws an abort error**. This applies regardless of whether a child process is active — aborting the signal generally produces an error even if it occurs between iterations or before the first `next()` call. `LOOPX_TMPDIR` cleanup, when applicable, runs before the abort error is thrown.
 
-- **AbortSignal:** When the `signal` is aborted, loopx terminates the active child process group (if one is running — SIGTERM, then SIGKILL after 5 seconds) and the generator **throws an abort error**. This applies regardless of whether a child process is active — aborting the signal always produces an error, even if it occurs between iterations or before the first `next()` call. This follows conventional JavaScript `AbortSignal` semantics.
+**Pre-first-`next()` consumer-cancellation carve-out.** A `.return(value)` or `.throw(err)` call as the consumer's *first* interaction with the generator returned by `run()` settles the generator per standard JS async-generator semantics; the loop body is never entered. No pre-iteration step runs and no pre-iteration error is surfaced: captured option-snapshot errors (invalid `options` values, invalid `options.signal`, non-string `options.cwd` / `options.envFile`, invalid `options.maxIterations`, invalid `options.env` shape, throwing option-field getters, throwing `options.env` enumerable getters or proxy traps), invalid `target` values and target-syntax validation, `.loopx/` discovery failures, env-file loading failures, target resolution failures, and tmpdir creation failures are all suppressed. A `signal` captured at call time is not consulted; even an already-aborted signal does not surface the abort error through this path. This carve-out applies only to `run()`; `runPromise()` has no equivalent. Once the consumer's first interaction is `next()`, the body is entered and captured state is observed.
 
 ### 9.2 `runPromise(target: string, options?: RunOptions)`
 
@@ -756,14 +882,29 @@ Returns a `Promise<Output[]>` that resolves with an array of all `Output` values
 
 `target` is required, same as `run()`. In JavaScript or when the type check is bypassed, `runPromise(undefined as any)` returns a rejected promise rather than throwing synchronously — the call itself always returns a promise, and the validation error surfaces as a rejection.
 
+**Option-snapshot timing.** Identical to `run()` (section 9.1): each option field read at most once, `options.signal` first, throwing getters / traps captured rather than escaping at the call site.
+
+**Inherited-env and tmpdir-parent snapshot timing.** Under `runPromise()`, the inherited `process.env` snapshot is **eager** — captured synchronously at the `runPromise()` call site, before `runPromise()` returns. Mutations to `process.env` after `runPromise()` returns are not observed. The tmpdir parent is captured on the same schedule, so a synchronous `process.env.TMPDIR = …` mutation after `runPromise()` returns does not affect the tmpdir parent for that run. Global env file path resolution (`XDG_CONFIG_HOME` / `HOME`) also uses this schedule. `LOOPX_TMPDIR` itself is created asynchronously after return, during the same pre-iteration sequence used by the CLI and `run()`.
+
+There is no `runPromise()` equivalent of the `run()` pre-first-`next()` consumer-cancellation carve-out: any pre-iteration error surfaces via promise rejection.
+
 ### 9.3 Error Behavior
 
 The programmatic API has different behavior from the CLI:
 
 - **The library never prints `result` to stdout.** All results are returned as structured `Output` objects.
-- **Errors throw/reject.** Any condition that would cause the CLI to exit with code 1 (non-zero script exit, invalid `goto`, missing workflow, missing script, validation failures) causes `run()` to throw from the generator and `runPromise()` to reject.
+- **Errors throw/reject.** Any condition that would cause the CLI to exit with code 1 (non-zero script exit, invalid `goto`, missing workflow, missing script, validation failures, `LOOPX_TMPDIR` creation failure, child launch / spawn failure after tmpdir creation including runtime env-entry rejections from any tier, `RunOptions.env` shape and snapshot-time errors, invalid `options` and invalid `options.signal`, non-string `options.cwd` / `options.envFile`) causes `run()` to throw from the generator and `runPromise()` to reject.
 - **Partial outputs are preserved.** When `run()` throws, all previously yielded outputs have already been consumed by the caller. When `runPromise()` rejects, partial outputs are not available (use `run()` if partial results matter).
 - **Stderr passes through.** Script stderr is still forwarded to the parent process's stderr, same as in CLI mode.
+- **Cleanup ordering is observable.** When `LOOPX_TMPDIR` cleanup runs as part of an error path (per section 7.4), it runs **before** the generator throws or the promise rejects. Cleanup warnings emitted during this window do not mask the original throw / rejection reason.
+
+**Abort precedence over pre-iteration failures.** Once a usable `AbortSignal` has been captured (a real `AbortSignal` or a duck-typed signal that satisfies the section 9.5 contract), an already-aborted signal at call time, or a signal that aborts during pre-iteration before the first child spawn, displaces all other pre-iteration failure modes on the same call: captured option-snapshot errors, target argument / target syntax validation, `.loopx/` discovery, env-file loading, target resolution, and tmpdir creation. An invalid `options` value or non-`AbortSignal`-compatible `options.signal` captures no signal and does not enter this pathway — it remains an ordinary option-snapshot error. Version checking is not a failure mode per section 3.2, so it does not compete.
+
+**Abort precedence × `maxIterations: 0`.** Abort precedence also applies before the `maxIterations: 0` zero-iteration short-circuit. If a usable signal has already aborted at call time, or aborts before the first child spawn, `maxIterations: 0` does not cause normal zero-iteration completion. Under `runPromise()`, the promise rejects with the abort error rather than resolving with `[]`. Under `run()`, the first `next()` throws the abort error rather than resolving `{ done: true }`. No child is spawned and no `LOOPX_TMPDIR` is created on this path. This rule is still subject to the `run()` pre-first-`next()` consumer-cancellation carve-out: a `.return()` or `.throw()` as the consumer's first interaction suppresses the abort as described in section 9.1.
+
+**Pinned pre-iteration priority.** Among non-abort pre-iteration errors, project-root-blocking and envFile-path-blocking option errors must surface before the four project-root-dependent failures: a non-string `options.cwd` or throwing `options.cwd` getter, and a non-string `options.envFile` or throwing `options.envFile` getter, surface before `.loopx/` discovery errors, env-file loading errors, target resolution errors, or tmpdir-creation errors. (Otherwise, an unrelated non-options error detected under a garbage project root would obscure the actual cause.) The pinning is scoped to that set only; relative priority between these pinned option errors and target argument / target syntax validation is implementation-defined. Relative priority among the remaining non-abort pre-iteration errors (invalid `options`, invalid `options.signal`, invalid `options.maxIterations`, invalid `options.env` shape and snapshot-time throws, target argument / target syntax validation, and the four project-root-dependent failures) is implementation-defined.
+
+**Abort after final yield.** An `AbortSignal` that aborts after the final `Output` has been yielded (via `stop: true` or `maxIterations` reached) but before the generator settles via `{ done: true }` produces the abort error on the next generator interaction — `g.next()`, `.return()`, or `.throw()`. Normal completion is fixed only at settlement, not at the final yield. `LOOPX_TMPDIR` cleanup runs before the abort error is surfaced.
 
 ### 9.4 `output(value)` and `input()`
 
@@ -785,13 +926,49 @@ interface RunOptions {
   envFile?: string;
   signal?: AbortSignal;
   cwd?: string;
+  env?: Record<string, string>;
 }
 ```
 
-- When `signal` is provided and aborted, the active child process group is terminated and the generator/promise completes with an abort error.
-- `cwd` specifies the **project root**: the directory from which `.loopx/` is resolved and from which `LOOPX_PROJECT_ROOT` is derived. It does not control the child process working directory — scripts always execute with their workflow directory as cwd (section 6.1). Defaults to `process.cwd()` at the time `run()` or `runPromise()` is called. Code that passes `cwd` expecting it to set the script's working directory must be updated — relative path resolution within the script will be relative to the workflow directory, and `LOOPX_PROJECT_ROOT` (sourced from `RunOptions.cwd` or `process.cwd()`) should be used for project-root-relative paths.
-- `maxIterations` counts every target execution, including goto hops. `maxIterations: 0` mirrors CLI `-n 0` behavior: validates and exits without executing any iterations. `maxIterations` must be a non-negative integer; invalid values (negative, non-integer, NaN) cause `run()` to throw on first iteration and `runPromise()` to reject.
-- Relative `envFile` paths are resolved against `cwd` if provided, otherwise against `process.cwd()` at call time.
+**`options` validity.** `options` must be omitted, `undefined`, or a non-null, non-array, non-function object. Non-conforming values, including throwing getters on the options object, are captured at call time and surfaced via the standard pre-iteration error path rather than escaping at the call site.
+
+**`signal`.**
+
+- When present and not `undefined`, `signal` must be an `AbortSignal`-compatible object. Compatibility requires:
+  - Reading `signal.aborted` must not throw, and the value read must be a boolean. No coercion is applied: missing / `undefined` values, strings such as `"false"`, numbers such as `0`, and any other non-boolean values mean the object is not `AbortSignal`-compatible.
+  - `addEventListener` must expose an `addEventListener('abort', listener)` method that is callable and returns without throwing when loopx invokes it to register its abort listener.
+
+  A non-compatible `signal` captures no usable signal and is surfaced as an ordinary option-snapshot error under the standard pre-iteration error path.
+- `removeEventListener` is not part of the `AbortSignal`-compatibility contract: loopx does not require its presence, and whether loopx invokes it on settlement is implementation-defined.
+- When `signal` is provided and aborted, the active child process group is terminated and the generator / promise completes with an abort error (subject to the abort precedence rules in section 9.3 and the `run()` pre-first-`next()` carve-out in section 9.1).
+- **Duck-typed signal reentrancy.** For non-`AbortSignal` duck-typed signals: if `addEventListener` synchronously invokes the registered listener during registration, or if `aborted` is observed as `true` at any point during call-time capture, loopx treats the signal as aborted. Real `AbortSignal` instances passed in an already-aborted state must be observed as aborted regardless of implementation latitude. Other reentrant behavior — `aborted` transitioning between reads within the same call, ordering between reading `aborted` and registering the listener for duck-typed signals — is implementation-defined.
+
+**`cwd`.**
+
+- When present and not `undefined`, must be a string. A non-string value, or a throwing `cwd` getter, is captured at call time and surfaced via the pre-iteration error path.
+- Specifies both the **project root** and the **script execution cwd**. The directory from which `.loopx/` is resolved, from which `LOOPX_PROJECT_ROOT` is derived, and which every spawned script uses as its working directory (section 6.1). The previous "`cwd` does not control script execution cwd" disclaimer no longer applies.
+- A relative `cwd` is resolved via `path.resolve(process.cwd(), options.cwd)` once at call time; an absolute `cwd` is used unchanged. No `realpath` / canonicalization is applied (see section 3.2).
+- Defaults to `process.cwd()` at the time `run()` or `runPromise()` is called.
+
+**`envFile`.**
+
+- When present and not `undefined`, must be a string. A non-string value, or a throwing `envFile` getter, is captured at call time and surfaced via the pre-iteration error path.
+- Relative `envFile` paths are resolved against the resolved project root (which equals the child's cwd) when `cwd` is supplied, otherwise against `process.cwd()` at call time.
+
+**`maxIterations`.**
+
+- Must be a non-negative integer. Invalid values (negative, non-integer, NaN) cause `run()` to throw on first iteration and `runPromise()` to reject.
+- Counts every target execution, including goto hops. `maxIterations: 0` mirrors CLI `-n 0` behavior: validates and exits without executing any iterations. No `LOOPX_TMPDIR` is created under `maxIterations: 0`. `maxIterations: 0` remains subject to the abort-precedence rules in section 9.3.
+
+**`env`.**
+
+- **Shape.** Must be omitted, `undefined`, or a non-null, non-array, non-function object whose own enumerable string-keyed entries all have string values. Symbol-keyed, non-enumerable, and inherited properties are ignored. Invalid shapes (null, array, non-object, function, or an entry with a non-string value) are captured at call time and surfaced via the standard pre-iteration error path.
+- **Lifetime.** Entries are captured synchronously at call time as a shallow copy — loopx reads the supplied object's own enumerable string-keyed properties once. After loopx has identified the included own enumerable string-keyed keys, it reads each included key's value using ordinary ECMAScript property `[[Get]]` semantics, equivalent to `env[key]`, exactly once during the call-time snapshot. Therefore, for a `Proxy` used as `options.env`, a `get` trap for each included string key is invoked exactly once; if that trap throws, the exception is captured and surfaced via the standard pre-iteration error path. This rule does not require loopx to read symbol-keyed, non-enumerable, or inherited properties; those remain ignored. The strategy used to determine enumerability may invoke descriptor-related proxy traps and remains otherwise implementation-defined unless specified elsewhere. Mutating the original object after `run()` / `runPromise()` returns has no effect on the running loop. Any exception raised during the snapshot (a `Proxy` `ownKeys` trap that throws, a throwing enumerable getter, a throwing `Proxy` `get` trap on an included string key, a throwing `options.env` getter on the options object) is captured and surfaced through the standard pre-iteration error path; it never escapes at the call site.
+- **Merge position.** Entries merge into the child environment after global and local env-file loading and before loopx-injected protocol variables (see section 8.3 precedence list). A `RunOptions.env` entry overrides same-named values from `-e`, the global env file, and inherited `process.env`, and is overridden by protocol variables.
+- **Applies to every script in the run.** Starting target, intra- and cross-workflow `goto` destinations, and loop resets all receive the same `env` additions.
+- **No name validation beyond string-to-string.** loopx does not enforce the POSIX `[A-Za-z_][A-Za-z0-9_]*` name pattern, does not reject `LOOPX_*` keys (they are silently overridden by protocol injection), does not reject `=` or empty-string names, and does not reject NUL bytes. Runtime-level rejections — most reliably a name or value containing an embedded NUL byte — surface as child launch / spawn failures at spawn time (any env tier may be the source; the runtime does not distinguish tiers). `RunOptions.env` shape validation (invalid object types, non-string values, snapshot-time throws) is independent of spawning and surfaces under `maxIterations: 0` just as under any other iteration count. The CLI has no `RunOptions.env` to validate, so this shape-validation path does not apply to `-n 0`; `-n 0` does still validate env files.
+- **No CLI surface.** Programmatic-only. CLI callers pass per-run values via the shell env prefix (`key=value loopx run …`), which flows through inherited `process.env`, or via `-e` / `loopx env set` for file-based config.
+- **`LOOPX_DELEGATED` is not script-protocol-protected.** Per section 3.2, `LOOPX_DELEGATED` is set only on the inner loopx process during project-root delegation, not on every script spawn. It is not added to the per-spawn protected tier; env files, inherited `process.env`, and `RunOptions.env` may supply it to spawned scripts.
 
 ---
 
@@ -803,7 +980,7 @@ loopx install [options] <source>
 
 Installs one or more workflows into the `.loopx/` directory, creating it if necessary.
 
-`<source>` is required. `loopx install` with no source is a usage error (exit code 1). See section 4.2 for install-scoped options (`-w`, `-y`, `-h`) and their parsing rules.
+`<source>` is required. `loopx install` with no source is a usage error (exit code 1). See section 4.2 for install-scoped options (`-w`, `-y`, `--no-install`, `-h`) and their parsing rules.
 
 ### 10.1 Source Detection
 
@@ -896,6 +1073,8 @@ There is no `.loopx/package.json` manifest. Version authority lives in two place
 
 ### 10.7 Install Atomicity
 
+This section's atomicity scope covers only the **file-level install** (source acquisition → preflight → stage → commit). Post-commit auto-install behaviors specified in section 10.10 (`.gitignore` safeguard synthesis, `npm install`) run after the commit phase and are **outside** this section's preflight-atomicity guarantee: they do not roll back committed workflow files. The "preflight-atomic" invariant and the stage-then-commit mechanics themselves are unchanged; only the scope boundary is made explicit. See section 10.10 for post-commit failure semantics.
+
 Multi-workflow installs are **preflight-atomic**: no workflows are written until all selected workflows pass preflight and staging completes. Once commit begins, a rare failure may leave a partial install; loopx reports which workflows were and were not committed.
 
 **Preflight phase:** All preflight checks — name restriction violations, script-name collisions within a workflow, collisions with existing entries at `.loopx/<workflow-name>`, and version mismatches (workflow declares a `loopx` range not satisfied by the running version) — are evaluated for every selected workflow (that is, every workflow that would be installed) before any are written. If any workflow fails any preflight check, the entire install fails, no workflows are written to `.loopx/`, and a single aggregated error is displayed listing all failures across all workflows. When `-y` is present, replaceable workflow-path collisions and version mismatches are recorded during preflight but are not treated as failures; all other validation failures (invalid names, same-base-name collisions, zero-workflow sources, non-workflow destination paths) remain fatal regardless of `-y`. Directories with no script files are silently skipped (they are not workflows) and do not cause a failure.
@@ -922,8 +1101,54 @@ When `-w` is used, only the selected workflow is validated. Invalid sibling work
 
 ### 10.9 Common Rules
 
-- **loopx does not run `npm install` or `bun install` after cloning/extracting.** For workflows with dependencies, the user must install them manually (e.g., `cd .loopx/my-workflow && npm install`).
-- **Install failure cleanup:** Any install failure (download error, HTTP non-2xx, git clone failure, extraction failure, post-download validation failure) exits with code 1. Any partially created staging directory is removed before exit. For single-workflow installs, any partially created target directory at the destination path is also removed before exit.
+- **Install failure cleanup (pre-commit failure modes):** Any pre-commit install failure (download error, HTTP non-2xx, git clone failure, extraction failure, post-download validation failure) or staging-phase failure under section 10.7 exits with code 1. Any partially created staging directory is removed before exit. Under the section 10.7 stage-then-commit model, pre-commit failures leave `.loopx/` itself unchanged, so no destination-path cleanup is needed for either single- or multi-workflow installs. This cleanup contract applies **only** to the pre-commit failure modes enumerated here. Post-commit auto-install failures specified in section 10.10 (`.gitignore` safeguard failure, `npm install` non-zero exit, `npm install` spawn failure) still cause exit `1` but do **not** remove already-committed workflow directories from `.loopx/` and do **not** remove a partial `node_modules/` left behind by an interrupted install; those behaviors are governed by section 10.10's aggregate-report / no-rollback rule.
+- **HTTP redirect handling.** For tarball downloads, loopx does not follow HTTP redirects in v1. Any HTTP response status outside the 2xx range is treated as an HTTP non-2xx install failure, including 3xx responses. `Location:` headers on 3xx responses are ignored.
+
+### 10.10 Auto-install Workflow Dependencies
+
+After the commit phase (section 10.7) completes successfully, unless `--no-install` is present, loopx performs a post-commit auto-install pass over the committed workflows. For each committed workflow with a top-level `package.json`, loopx attempts to populate `node_modules/` by running `npm install`. The trigger is the presence of a top-level `package.json`; whether that file declares any dependencies is not inspected. The pass is best-effort: whether `npm install` actually runs and succeeds for a given workflow is governed by the per-workflow trigger conditions, opt-outs, skips, and failure modes detailed below.
+
+If the commit phase fails after committing only a subset of workflows, the post-commit auto-install pass is skipped entirely. loopx does not run `npm install` and does not synthesize `.gitignore` safeguards for any workflow, including workflows that were committed before the commit failure. The command reports the commit-phase failure according to section 10.7 and exits with code 1.
+
+- **Trigger.** Runs once per committed workflow whose top-level `package.json` exists at `.loopx/<workflow-name>/package.json`, sequentially in an implementation-defined order, with cwd set to the workflow directory. The cross-workflow order of the post-commit auto-install pass is not an external conformance contract; implementations may use their internal commit order or any other implementation-defined order. The required external guarantees are that each committed workflow with a qualifying top-level `package.json` is considered once, npm children do not overlap, and processing follows the failure / signal rules in this section. Workflows without a top-level `package.json` are skipped silently — no warning, no `npm install` invocation, no `.gitignore` synthesis. When `-w <name>` restricts the install to a single workflow, auto-install considers only that workflow.
+- **Package manager.** `npm install` unconditionally. loopx does not inspect `bun.lockb`, `pnpm-lock.yaml`, `yarn.lock`, or a `packageManager` field to select a different manager, and does not pass `--production` / `--omit=dev` / `--ignore-scripts` / any other flags — whatever the workflow's `package.json` and the user's npm configuration prescribe is what runs. Workflow authors needing a different manager pass `--no-install` and invoke their preferred tool manually.
+- **Environment.** The `npm install` child inherits loopx's own `process.env` unchanged. `LOOPX_*` protocol variables, `RunOptions.env`, and env-file entries are not injected — these are script-execution-context concerns, not install-time concerns.
+- **Output.** npm's stdout and stderr stream through to loopx's stdout and stderr unchanged; loopx neither buffers nor parses npm output and does not introduce a progress indicator of its own.
+- **`--no-install` opt-out.** A new install-scoped boolean flag (section 4.2) suppresses auto-install for every selected workflow in the current command. `--no-install` does not suppress any other install-time behavior (source download, preflight validation, stage-then-commit); only the `npm install` step and the `.gitignore` safeguard described below are skipped.
+- **`.gitignore` safeguard for `node_modules/`.** Immediately before spawning `npm install` in a workflow directory, loopx checks the top-level `.gitignore` path using `lstat`.
+  - **Path does not exist (`ENOENT`):** loopx creates a regular file at `.gitignore` containing the single line `node_modules`.
+  - **Path exists and is a regular file:** loopx leaves it unchanged and proceeds. loopx does not read, parse, validate, append to, or inspect the file's contents or permissions; the workflow author is responsible for any pre-existing regular `.gitignore`.
+  - **Path exists but is not a regular file** (directory, symlink, FIFO, socket, or other non-regular entry): loopx treats this as a `.gitignore` safeguard failure. The entry is left unchanged, `npm install` is skipped for that workflow, the failure is recorded in the auto-install aggregate report, loopx proceeds to the next workflow, and the failure contributes to final exit code `1`.
+  - **`lstat` failure other than `ENOENT`, or a write failure when synthesizing `.gitignore`:** loopx treats this as a `.gitignore` safeguard failure under the same aggregate-report / skip-`npm install` semantics.
+
+  A symlink named `.gitignore` does not satisfy the safeguard, even if it resolves to a regular file. Broken and cyclic symlinks are treated as symlink entries and therefore fail the safeguard. The safeguard is skipped entirely under `--no-install` and for workflows that do not have a top-level `package.json` (matching the trigger conditions for `npm install`).
+
+  Committed workflow files are not rolled back on a `.gitignore` safeguard failure. The user can remediate by replacing the `.gitignore` entry with a regular file (or removing it so loopx synthesizes one) and running `cd .loopx/<workflow> && npm install`, or by re-running `loopx install -y <source>`.
+- **Failure (npm install).** If `npm install` exits non-zero, or fails to spawn (most commonly: `npm` is not on `PATH`), loopx records the failure, proceeds with the next workflow's `npm install`, and exits `1` at the end if any workflow's `npm install` failed. Dependency-install failures do not roll back the file-level install: committed workflows remain on disk in the same partial-install sense as section 10.7's commit-failure clause. Retries: `loopx install -y <source>` reinstalls from scratch, or `cd .loopx/<workflow> && npm install` retries manually.
+- **Aggregate failure report.** After the post-commit auto-install pass finishes, if any `.gitignore` synthesis or `npm install` failed for any workflow, loopx emits a final aggregate failure report to stderr that lists each affected workflow together with the underlying failure (`.gitignore` safeguard failure, `npm install` non-zero exit, or `npm install` spawn failure) and then exits `1`. Workflows whose safeguard and `npm install` both succeeded are not listed. If no auto-install failures occurred, no aggregate report is emitted. The aggregate report does not roll back committed workflow files or any partial `node_modules/` left on disk; remediation is the manual procedure described in the preceding bullet and in the `.gitignore` safeguard bullet.
+- **Malformed `package.json`.** When the workflow's `package.json` is unreadable, contains invalid JSON, or has an invalid `loopx` semver range (the section 3.2 failure modes), the existing section 3.2 warning is emitted and auto-install **skips that workflow silently** — loopx does not invoke `npm install` against a file that failed version validation and does not add a second warning for the same underlying failure. The `.gitignore` safeguard is also skipped for the same workflow. A skipped workflow is not an auto-install failure and does not appear in the aggregate failure report.
+- **Interaction with `-y`.** File-level replacement removes the existing workflow directory (including any previously installed `node_modules/` and any previously synthesized `.gitignore`) before the replacement is committed; the safeguard and `npm install` then run fresh against the replacement's `package.json` and `.gitignore` (or absence thereof).
+- **Signals during `npm install`.** SIGINT / SIGTERM received while an `npm install` child is active propagates to the child's process group. loopx waits for the child to exit (the section 7.3 grace period and SIGKILL escalation rules apply by analogy) and then exits with the signal's code. Remaining committed workflows are not processed (no further `.gitignore` synthesis or `npm install` invocations). Partial `node_modules/` state produced before interruption is not cleaned up by loopx.
+- **Signals during the auto-install pass when no npm child is active.** SIGINT / SIGTERM observed by loopx during the post-commit auto-install pass aborts the auto-install pass. If no `npm install` child is active when the signal is observed — including between workflows, after an npm child exits and before the next workflow begins, during or after `.gitignore` safeguard processing, or after a safeguard failure before the next workflow — loopx exits with `128 + signal number`, starts no further `.gitignore` safeguards, starts no further `npm install` children, and does not roll back committed workflow files. Any `.gitignore` or `node_modules/` side effects completed before the signal was observed remain on disk. If a synchronous or already-started safeguard operation completes before loopx observes the signal, its side effects remain. Signal termination suppresses the final auto-install aggregate failure report unless it had already been emitted.
+- **Trust profile.** Because `npm install` may execute arbitrary code via `preinstall` / `install` / `postinstall` scripts declared in the workflow's dependency graph, `loopx install` inherits the same trust profile as a manual `npm install` in the same directory. Users installing from untrusted sources should pass `--no-install` and inspect the workflow before running `npm install` themselves.
+
+### 10.11 Install Source Symlinks
+
+Install source symlinks are handled explicitly during classification, validation, staging, and copy. This rule applies after a git source has been cloned or a tarball source has been extracted and any wrapper directory has been stripped.
+
+For install-time workflow and script discovery, loopx follows symlinks using the same entry-type policy as runtime discovery: a symlinked workflow directory can qualify as a workflow, and a symlinked script file can qualify as a script. Names are derived from the symlink entry's own name, not from the target's basename.
+
+During the staging / copy phase, loopx does **not** preserve symlink entries as symlinks in installed workflows. Any symlink that is part of a selected workflow is resolved and materialized into the destination as a regular copied file or directory:
+
+- A selected top-level workflow entry that is a symlink to a directory is installed as a real directory at `.loopx/<workflow-name>/`, containing a copy of the symlink target's workflow contents.
+- A selected script entry that is a symlink to a file is installed as a real file at the corresponding destination script path, containing a copy of the symlink target's file contents.
+- Symlinked non-script files or directories inside a selected workflow's copied content are likewise materialized as real files or directories.
+
+Symlink targets must resolve to existing paths within the install source root. loopx must reject the install with a preflight / validation error when a symlink that is part of a selected workflow is broken, forms a cycle, or resolves outside the source root. This prevents installed workflows from depending on the temporary clone / extraction directory or from copying arbitrary files outside the source.
+
+When `-w <name>` / `--workflow <name>` is used, only symlinks that are part of the selected workflow are validated and materialized. Symlinks in unselected workflow directories or source-root support directories are ignored, consistent with the selective validation rule in section 10.8.
+
+Installed workflow symlinks are therefore not preserved as symlinks, and no installed symlink points back into loopx's temporary acquisition or staging directories.
 
 ---
 
@@ -944,7 +1169,7 @@ Top-level help does **not** inspect `.loopx/` or perform discovery.
 
 `loopx run -h` / `loopx run --help` prints run-specific usage information:
 
-- `run` syntax and options (`-n`, `-e`)
+- `run` syntax and options (`-n`, `-e`). Per section 4.1, `run` does not accept `--` as an end-of-options marker and does not accept a named-argument tail; the shell env prefix (`key=value loopx run <target>`) is the sole CLI surface for per-run parameterization. The printed usage reflects these limits.
 - A dynamically generated list of workflows and their scripts discovered in the current `.loopx/` directory. If a workflow has an `index` script, it is indicated as the default entry point.
 
 Run help performs **non-fatal discovery and validation**:
@@ -960,10 +1185,10 @@ Run help is the only help form that performs workflow and script discovery. The
 
 `loopx install -h` / `loopx install --help` prints install-specific usage information:
 
-- `install` syntax and options (`-w`, `-y`)
+- `install` syntax and options (`-w`, `-y`, `--no-install`)
 - Supported source types
 
-Install help does not require a source argument, does not make network requests, and does not inspect `.loopx/`.
+Install help does not require a source argument, does not make network requests, and does not inspect `.loopx/`. The `install -h` / `--help` short-circuit continues to ignore `--no-install` (and every other install-level argument) unconditionally.
 
 ---
 
@@ -972,12 +1197,12 @@ Install help does not require a source argument, does not make network requests,
 | Code | Meaning |
 |------|---------|
 | 0 | Clean exit: loop ended via `stop: true`, `-n` limit reached (including `-n 0`), successful subcommand execution, or help display. |
-| 1 | Error: script exited non-zero, validation failure, invalid `goto` target, missing workflow, missing script, missing `.loopx/` directory, install failure, or usage error. |
-| 128+N | Interrupted by signal N (e.g., 130 for SIGINT). |
+| 1 | Error: script exited non-zero, validation failure, invalid `goto` target, missing workflow, missing script, missing `.loopx/` directory, `LOOPX_TMPDIR` creation failure, child launch / spawn failure after tmpdir creation, install failure (including `npm install` non-zero exit or spawn failure under section 10.10, and `.gitignore` safeguard failure under section 10.10), or usage error. |
+| 128+N | Interrupted by signal N (e.g., 130 for SIGINT). When `LOOPX_TMPDIR` has been created, cleanup runs before exit per section 7.4. A signal received during `npm install` causes loopx to wait for the npm child to exit before exiting with the signal's code (section 10.10). Cleanup warnings do not affect the exit code or the programmatic outcome. |
 
-Usage errors (exit code 1) include: `loopx run` with no target, `loopx run ralph bar` (extra positional), `loopx foo` (unrecognized subcommand), `loopx ralph` (unrecognized subcommand — no implicit fallback to `run`), `loopx --unknown` (unrecognized top-level flag), `loopx -n 5 ralph` (top-level `-n`), `loopx -e .env ralph` (top-level `-e`), `loopx run --unknown ralph` (unrecognized run flag), `loopx run -n 5 -n 10 ralph` (duplicate run flag), `loopx install` with no source, `loopx install -w a -w b <source>` (duplicate install flag), and `loopx install --unknown <source>` (unrecognized install flag).
+Usage errors (exit code 1) include: `loopx run` with no target, `loopx run ralph bar` (extra positional), `loopx run -- ralph` (unrecognized `--`), `loopx run -n 1 -- ralph` (unrecognized `--`), `loopx run ralph -- name=value` (unrecognized `--`), `loopx run ralph adr=0003` (extra positional — `name=value` is not interpreted as a named argument), `loopx foo` (unrecognized subcommand), `loopx ralph` (unrecognized subcommand — no implicit fallback to `run`), `loopx --unknown` (unrecognized top-level flag), `loopx -n 5 ralph` (top-level `-n`), `loopx -e .env ralph` (top-level `-e`), `loopx run --unknown ralph` (unrecognized run flag), `loopx run -n 5 -n 10 ralph` (duplicate run flag), `loopx install` with no source, `loopx install -w a -w b <source>` (duplicate install flag), `loopx install --no-install --no-install <source>` (duplicate install flag), and `loopx install --unknown <source>` (unrecognized install flag).
 
-Invalid target strings (e.g., `loopx run ":script"`, `loopx run "workflow:"`, `loopx run "a:b:c"`, `loopx run ""`) are also exit code 1 but are not usage errors — they are rejected after discovery, at the same point as a missing workflow or missing script (section 4.1).
+Invalid target strings (e.g., `loopx run ":script"`, `loopx run "workflow:"`, `loopx run "a:b:c"`, `loopx run ""`, `loopx run adr=0003` parsed as a target) are also exit code 1 but are not usage errors — they are rejected after discovery, at the same point as a missing workflow or missing script (section 4.1).
 
 Note: A non-zero exit code from any script causes loopx to exit with code 1. Scripts that need error resilience should handle errors internally and exit 0.
 
@@ -985,11 +1210,17 @@ Note: A non-zero exit code from any script causes loopx to exit with code 1. Scr
 
 ## 13. Summary of Reserved and Special Values
 
-| Name | Context | Purpose |
-|------|---------|---------|
-| `LOOPX_BIN` | Env variable | Resolved realpath of the effective loopx binary (post-delegation) |
-| `LOOPX_PROJECT_ROOT` | Env variable | Absolute path to the project root (section 3.2) |
-| `LOOPX_WORKFLOW` | Env variable | The name of the workflow containing the currently executing script |
-| `LOOPX_DELEGATED` | Env variable | Set to `1` during delegation to prevent recursion |
-| `index` | Convention | Default entry point script name within a workflow |
-| `:` | Delimiter | Reserved separator between workflow and script names in target strings |
+Reserved env-var names play one of two distinct roles. **Script-protocol-protected** names are injected on every child spawn and silently override any user-supplied value at the section 8.3 top tier. **Startup-reserved-only** names are inspected on loopx's own startup but are not injected into per-spawn script environments and are not protected from user override on the child.
+
+| Name | Context | Role | Purpose |
+|------|---------|------|---------|
+| `LOOPX_BIN` | Env variable | Script-protocol-protected | Resolved realpath of the effective loopx binary (post-delegation) |
+| `LOOPX_PROJECT_ROOT` | Env variable | Script-protocol-protected | Absolute path to the project root (section 3.2) |
+| `LOOPX_WORKFLOW` | Env variable | Script-protocol-protected | The name of the workflow containing the currently-spawned script. Refreshed per-spawn. |
+| `LOOPX_WORKFLOW_DIR` | Env variable | Script-protocol-protected | Absolute path of the workflow directory containing the currently-spawned script (section 6.1). Refreshed per-spawn alongside `LOOPX_WORKFLOW`. |
+| `LOOPX_TMPDIR` | Env variable | Script-protocol-protected | Absolute path to the run-scoped temporary directory (section 7.4). Stable for the lifetime of the run. |
+| `LOOPX_DELEGATED` | Env variable | Startup-reserved only | Inspected on loopx's own startup as a delegation recursion guard (section 3.2). Set on the inner loopx process during project-root delegation, not on every script spawn. Env files, inherited `process.env`, and `RunOptions.env` may supply this name to spawned scripts; it is not protected at the section 8.3 top tier. |
+| `index` | Convention | — | Default entry point script name within a workflow |
+| `:` | Delimiter | — | Reserved separator between workflow and script names in target strings |
+
+**`PWD` is intentionally not reserved.** loopx neither sets nor unsets `PWD`; the value loopx's own process holds is inherited unchanged. `PWD` is outside the script-protocol-protected tier, outside the startup-reserved tier, and outside section 8.3's protocol-variable tier. See sections 6.1 and 8.3.
diff --git a/TEST-SPEC.md b/TEST-SPEC.md
index 14ff1c0..e7dc6df 100644
--- a/TEST-SPEC.md
+++ b/TEST-SPEC.md
@@ -27,19 +27,25 @@
 
 ### 1.3 Coverage Scope
 
-This suite is the **implementation-driving** test suite — it defines the behavior that must pass before a feature is considered complete. It targets complete coverage of all SPEC.md requirements, including:
+**Platform scope: POSIX-only (macOS, Linux).** Per SPEC 1, v1 is POSIX-only and Windows is not supported. This test suite is correspondingly **POSIX-only by design** — tests exercise POSIX behaviors (process groups, `getcwd(3)` canonicalization, `realpath`, signal disposition, `os.tmpdir()` under `TMPDIR` semantics, `stat(3)` device/inode identity, unix file modes, symlinks, shell-managed `$PWD`, etc.) and are not expected to pass on Windows. CI runs POSIX matrix only (macOS, Linux × Node.js ≥ 20.6 and Bun ≥ 1.0). No Windows coverage is targeted or advertised. If a test happens to pass on Windows it is incidental, not a guarantee; if it fails, that is not a bug against this suite.
+
+This suite is the **implementation-driving** test suite — it defines the behavior that must pass before a feature is considered complete. It targets **near-complete coverage** of SPEC.md requirements — complete except for explicitly marked known gaps that depend on privileged operations unavailable in standard CI or on narrow timing windows for which no test-only seam is currently declared. The known gaps are enumerated in-line at the relevant sections (mount-point non-detection T-TMP-43 and host-crash cleanup non-guarantee T-TMP-44, and the cleanup-safety symlink-`unlink`-failure branch within creation-failure handling under `LOOPX_TEST_TMPDIR_FAULT=mode-secure-fail` — the partial directory created by `mkdtemp` is never a symlink, so cleanup-safety rule-2 dispatch is unreachable in that composition without an additional swap-to-symlink seam between identity capture and the cleanup-safety dispatch — see section 4.7; the pre-handler-installation signal-window clause T-SIG-26, the narrow post-tmpdir-pre-spawn signal window T-SIG-29, the programmatic pre-iteration abort window T-API-10i, and the partial-tmpdir-creation-racing-signal/abort window T-SIG-30b / T-API-10j — see section 4.11; implementation-private install staging-directory cleanup T-INST-79a — see section 4.10) and again in the Appendix A traceability matrix's "Known gaps" annotations. Previously-tracked seam-dependent gaps (tmpdir creation sub-steps T-TMP-12d / T-TMP-12e, cleanup-failure branches T-TMP-40 / T-TMP-41 / T-TMP-42, cleanup-failure during creation-failure handling T-TMP-12d2 / T-TMP-12e2 / T-TMP-12e3, cleanup idempotence / warning cardinality T-TMP-38 / T-TMP-39 / T-TMP-38a / T-TMP-38b / T-TMP-38c / T-TMP-38d / T-TMP-38d2 / T-TMP-38e, terminal-outcome precedence races T-TERM-01..T-TERM-04 across both observation orders including the `.throw()` axis T-TERM-02c / T-TERM-02d, and the auto-install aggregate-report-already-emitted carve-out T-INST-116l) have been promoted to direct conformance pins via the section 1.4 fault-injection seams `LOOPX_TEST_TMPDIR_FAULT` (extended with the `identity-capture-fail-rmdir-fail` compound value), `LOOPX_TEST_CLEANUP_FAULT`, and the pause sentinels `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE` (extended with `consumer-return-observed`, `consumer-throw-observed`, and `child-spawn-attempt` window values) and `LOOPX_TEST_AUTOINSTALL_PAUSE` (the last extended with a `post-aggregate-report` ordinal value). Beyond those tracked gaps, the suite covers, including:
 
 - **Spec 3.1 (Global Install):** Covered by T-INST-GLOBAL-01, which exercises the full `npm pack` → install into isolated global prefix → run against fixture project workflow. This runs in CI on every build.
 
-- **Spec 7.3 (Signal Handling — between iterations):** Covered by T-SIG-07, which sends a signal between iterations by coordinating via marker files. Tagged `@flaky-retry(3)` due to inherent timing sensitivity. The active-child signal cases (T-SIG-01–06) are fully covered without retry.
+- **Spec 7.3 (Signal Handling — between iterations):** Covered by T-SIG-07 (immediate-exit contract) and T-SIG-07a (tmpdir cleanup also runs on the between-iterations window — SPEC 7.3 / 7.4 "When no child is active, cleanup runs immediately"), both of which target the between-iterations window by (a) waiting for iteration 1's child PID to exit via polled `kill(pid, 0)` returning ESRCH, and then (b) delivering the signal before iteration 2's long-sleeping child has emitted its ready marker. Tagged `@flaky-retry(3)` due to the narrow residual race between iteration 2's fork-exec and its sleep installation — no between-iterations sentinel seam is declared, so this window is observed via PID-exit polling rather than a deterministic marker. The active-child signal cases (T-SIG-01–06) are fully covered without retry.
 
 - **Spec 9.1 (Async Generator Cancellation):** Multiple cancellation scenarios are tested: "break after yield" (T-API-06), "return during pending next" (T-API-09a), "abort signal during active child" (T-API-10a), "pre-aborted signal" (T-API-10b), and "abort between iterations" (T-API-10c).
 
+**Test-construction sanity for getter/proxy variants.** Several SPEC 9.5 "snapshot-time throws" tests assert that loopx captures a throwing enumerable getter or `Proxy` `ownKeys` trap during the synchronous option-snapshot pass and surfaces the captured exception via the standard pre-iteration error path — i.e., the exception originates **inside loopx**, not at the test call site. Because object-spread (`{ ...obj, foo }`) reads the spread source's own enumerable string-keyed properties at the spread expression, **spreading an object whose getter or proxy trap is the behavior under test invokes the throwing accessor in the test harness before `run()` / `runPromise()` is called**, which surfaces the exception at the test call site rather than letting loopx capture it. That short-circuit invalidates the assertion — the test would then be exercising the test harness's own evaluation order, not the SPEC 9.5 snapshot path. **Construction rule for getter / proxy variants**: build the final options object directly — install the throwing accessor on the same object passed to `run()` / `runPromise()` using `Object.defineProperty`, or assemble the options field-by-field — **never via object-spread of an object whose getters or proxy traps are the behavior under test**. The same rule applies to spreading an env value object whose entry getter throws or whose proxy `ownKeys` trap throws: pass the env object as the `env` field's value (a plain reference read), not as a spread source whose enumeration triggers the trap. Tests covering this surface (T-API-55c, T-API-55d, T-API-62, T-API-62e, T-API-62f, T-API-65f, T-API-65g, T-API-65p, T-API-65q, and others) use the field-by-field / `Object.defineProperty` construction pattern.
+
 ### 1.4 Internal Test Seams
 
-The implementation **must** expose the following pure functions as package-private imports for unit and fuzz testing. These are not part of the public API and are not documented in SPEC.md — they exist solely to enable high-volume testing.
+All items in this section are **test-only harness seams** — they are **non-public**, **required for this test suite**, and **not part of SPEC conformance**. A production consumer of loopx must never depend on them, and their presence or shape is not part of the public semver contract. They exist solely to enable high-volume fuzz testing (section 5.1, 5.2) and deterministic coverage of failure paths that are otherwise unreachable black-box.
 
-**Required exports (via a subpath like `loopx/internal` or a `src/internal.ts` barrel):**
+**Pure-function exports (non-public, test-only):**
+
+The test suite expects the following pure functions to be importable via a subpath like `loopx/internal` or a `src/internal.ts` barrel. The exact module path and export mechanism is an implementation detail (TypeScript `paths` aliases, a `package.json` `exports` subpath, or a direct relative import are all acceptable) — the only requirement is that the tests can reach them.
 
 | Function | Signature | Purpose |
 |----------|-----------|---------|
@@ -47,24 +53,118 @@ The implementation **must** expose the following pure functions as package-priva
 | `parseEnvFile` | `(content: string) => { vars: Record<string, string>, warnings: string[] }` | Parses `.env` file content per Spec 8.1 rules. Returns parsed variables and any warning messages for invalid lines |
 | `classifySource` | `(source: string) => { type: "git" \| "tarball", url: string }` | Classifies an install source per Spec 10.1 rules. Throws for rejected sources (e.g., single-file URLs) |
 
-**Design constraints:**
+**Design constraints (for the test suite's use):**
 
-- These functions must be **pure** — no I/O, no process spawning, no side effects. They take a string and return a value.
+- These functions should be **pure** — no I/O, no process spawning, no side effects. They take a string and return a value.
 - The `warnings` field in `parseEnvFile` returns the warning messages that would be printed to stderr during normal operation. This allows unit tests to assert on warning behavior without capturing stderr from a child process.
-- The exact module path and export mechanism is an implementation detail, but the test suite must be able to `import { parseOutput } from "loopx/internal"` (or equivalent). The implementation may use TypeScript `paths` aliases, a `package.json` `exports` subpath, or a direct relative import from the test files.
-- These exports are **not** part of the public semver contract. They may change shape between minor versions.
+- These exports are **not** part of the public semver contract. SPEC.md does not reference or constrain them; they exist solely for this test suite.
 
-**These seams are a hard implementation requirement.** Unit tests (section 6.1, 6.2) and high-volume fuzz tests (section 5.1, 5.2) depend on them. The implementation is not considered complete until these exports are available and importable by the test suite.
+These seams are what unit tests (section 6.1, 6.2) and high-volume fuzz tests (section 5.1, 5.2) import. Without them those tests fall back to slow E2E coverage or cannot exist at all — but a SPEC-conforming implementation without these exports still satisfies SPEC.md.
 
-**Install fault injection (environment variable seam):**
+**Install fault injection (test-only env-var seam, non-public, not part of SPEC conformance):**
 
-Install atomicity tests (T-INST-80c) must simulate commit-phase failures that are otherwise unreproducible in black-box tests (the commit phase involves only renames, which rarely fail on a healthy filesystem). The implementation must honor the following test-only environment variable:
+Install atomicity tests (T-INST-79, T-INST-80b, T-INST-80c, T-INST-80c2, T-INST-97a), auto-install safeguard tests (T-INST-112c, T-INST-112d, T-INST-112g, T-INST-112h, T-INST-112i, T-INST-112j, T-INST-112k), per-workflow auto-install spawn-failure tests (T-INST-114b), and auto-install no-active-child signal-window tests (T-INST-116h, T-INST-116i, T-INST-116j, T-INST-116k) must simulate failures or pause loopx at deterministic points that are otherwise unreproducible in black-box tests (staging-phase failures on healthy filesystems depend on archive-shape / permission tricks that are not SPEC-required to fail; commit-phase renames rarely fail on a healthy filesystem; `.gitignore` write failures depend on non-deterministic post-commit filesystem state; `lstat` failures other than `ENOENT` on the top-level `.gitignore` path depend on non-deterministic post-commit filesystem state and parent-directory permission state that are not reachable from ordinary install inputs; pre-existing symlink, FIFO, and socket `.gitignore` entries cannot be produced through ordinary install inputs because SPEC 10.11 materializes source symlinks before commit and ordinary install fixtures cannot place FIFOs or sockets at `.loopx/<workflow>/.gitignore`; pre-existing regular `.gitignore` entries with mode `000` depend on the implementation's staging-strategy preservation of source mode bits, which SPEC 10.7 does not require; selective per-invocation `npm` spawn failures cannot be driven by a `PATH`-based shim once a shim process has started; signal delivery during the auto-install pass when no `npm install` child is active hits sub-millisecond windows between safeguard / spawn / wait operations that cannot be deterministically targeted via real-time delays). The test suite assumes the implementation honors the following test-only environment variables:
 
 | Variable | Values | Behavior |
 |----------|--------|----------|
 | `LOOPX_TEST_INSTALL_FAULT` | `commit-fail-after:<n>` | During the install commit phase, simulate a rename failure (reported as `EACCES`) after `n` successful workflow commits. |
+| `LOOPX_TEST_INSTALL_FAULT` | `staging-fail:<workflow-name>[,<workflow-name>…]` | During the install staging phase (section 10.7 stage-then-commit), simulate a staging-write failure (reported as `EACCES`) for the named workflow(s) before any bytes are written to the staging directory for that workflow. This is the staging-phase counterpart to `commit-fail-after` and is what drives the T-INST-79 / T-INST-80b / T-INST-97a staging-failure coverage deterministically. SPEC 10.7 defines the failure outcome ("the staging directory is cleaned up and `.loopx/` is left unchanged. The install fails with an error identifying the failing workflow and the underlying cause"); the seam decouples that outcome from a specific source-shape fixture (e.g., tarball mode-000 files). Without this seam, the only black-box path is a mode-000 file, and SPEC does not require mode-000 to cause staging to fail — an implementation that streams from the archive, chmods extracted files before copying, or otherwise avoids a literal copy of the unreadable file is conforming and would not fail staging. Multiple values combine with `commit-fail-after` in a single `LOOPX_TEST_INSTALL_FAULT` value by listing them semicolon-separated (e.g., `staging-fail:alpha;commit-fail-after:1`) — the exact combination grammar is implementation-defined, but at minimum each fault type must be usable on its own. |
+| `LOOPX_TEST_AUTOINSTALL_FAULT` | `gitignore-write-fail:<workflow-name>[,<workflow-name>…]` | During the post-commit auto-install pass, simulate a `.gitignore` write failure (reported as `EACCES`) for the named workflow(s). The safeguard-write hook that section 10.10 describes as "Immediately before spawning `npm install`" checks the comma-separated list and, for any match, returns the `EACCES` write-failure path without actually attempting to create `.gitignore` on disk. This enables deterministic coverage of T-INST-112c without relying on real filesystem permissions (which vary across CI environments and are unreachable under `process.getuid() === 0`). |
+| `LOOPX_TEST_AUTOINSTALL_FAULT` | `npm-spawn-fail:<workflow-name>[,<workflow-name>…]` | During the post-commit auto-install pass, simulate an `npm` spawn failure (reported as `ENOENT`) for the named workflow(s). The spawn hook that section 10.10 describes as "`npm install` spawn failure (most commonly: `npm` is not on `PATH`)" checks the comma-separated list and, for any match, returns the spawn-failure path without actually invoking `spawn("npm", …)`. Multiple values combine in a single `LOOPX_TEST_AUTOINSTALL_FAULT` value by listing them semicolon-separated (e.g., `gitignore-write-fail:alpha;npm-spawn-fail:beta`) — the exact combination grammar is implementation-defined, but at minimum each fault type must be usable on its own. This enables deterministic per-workflow coverage of SPEC 10.10 "spawn failure on one workflow does not prevent `npm install` on subsequent workflows" (T-INST-114b), which a black-box `PATH`-based seam cannot drive: once a shim process has started, the spawn itself has already succeeded, so a shim cannot make only the second `spawn("npm")` fail with `ENOENT` while allowing the first and third to succeed. |
+| `LOOPX_TEST_AUTOINSTALL_FAULT` | `gitignore-replace-with-symlink:<workflow-name>[=<kind>][,<workflow-name>[=<kind>]…]` | During the post-commit auto-install pass for the named workflow(s), immediately **after** the commit phase has placed any source `.gitignore` content (per SPEC 10.11 materialization) and **before** the per-workflow safeguard `lstat`, replace `.loopx/<workflow-name>/.gitignore` (or create the path if it does not exist) with a symlink so that the safeguard's `lstat` observes a symlink entry. The optional `<kind>` selects which symlink shape is materialized: `regular-file-target` (default — symlink whose target is a regular file inside the workflow directory containing `node_modules`, exercising the "even if it resolves to a regular file" clause), `broken` (symlink to a non-existent target inside the workflow directory), or `cycle` (two symlinks `.gitignore -> .gitignore-loop` and `.gitignore-loop -> .gitignore` forming a cycle). Multiple values combine semicolon-separated with the other `LOOPX_TEST_AUTOINSTALL_FAULT` faults (e.g., `gitignore-replace-with-symlink:alpha=broken;npm-spawn-fail:beta`). This enables deterministic coverage of T-INST-112g — the symlink branch of SPEC 10.10's non-regular `.gitignore` enumeration ("A symlink named `.gitignore` does not satisfy the safeguard, even if it resolves to a regular file. Broken and cyclic symlinks are treated as symlink entries and therefore fail the safeguard") — which is otherwise unreachable through ordinary install inputs because SPEC 10.11 materializes source symlinks as regular files / directories before commit, so a committed symlink at `.loopx/<workflow>/.gitignore` cannot be produced by any black-box install fixture. |
+| `LOOPX_TEST_AUTOINSTALL_FAULT` | `gitignore-lstat-fail:<workflow-name>[,<workflow-name>…]` | During the post-commit auto-install pass for the named workflow(s), simulate an `lstat` failure other than `ENOENT` (reported as `EACCES`) when the safeguard inspects the top-level `.gitignore` path. The `lstat` hook that section 10.10 describes as "loopx checks the top-level `.gitignore` path using `lstat`" checks the comma-separated list and, for any match, returns the `EACCES` `lstat`-failure path without actually invoking `lstat` on disk. Multiple values combine semicolon-separated with the other `LOOPX_TEST_AUTOINSTALL_FAULT` faults (e.g., `gitignore-lstat-fail:alpha;npm-spawn-fail:beta`). This enables deterministic coverage of T-INST-112h — the SPEC 10.10 "`lstat` failure other than `ENOENT`" branch of the safeguard-failure enumeration — which is otherwise unreachable through ordinary install inputs (a non-`ENOENT` `lstat` failure on a workflow-root entry depends on parent-directory permission state and other non-deterministic filesystem conditions that are not reproducible across CI environments and are unreachable under `process.getuid() === 0`). |
+| `LOOPX_TEST_AUTOINSTALL_FAULT` | `gitignore-replace-with-fifo:<workflow-name>[,<workflow-name>…]` | During the post-commit auto-install pass for the named workflow(s), immediately **after** the commit phase has placed any source `.gitignore` content (per SPEC 10.11 materialization) and **before** the per-workflow safeguard `lstat`, replace `.loopx/<workflow-name>/.gitignore` (or create the path if it does not exist) with a FIFO (named pipe, e.g., via `mkfifo(2)`) so that the safeguard's `lstat` observes a FIFO entry. Multiple values combine semicolon-separated with the other `LOOPX_TEST_AUTOINSTALL_FAULT` faults. This enables deterministic coverage of T-INST-112i — the FIFO branch of SPEC 10.10's non-regular `.gitignore` enumeration ("directory, symlink, FIFO, socket, or other non-regular entry") — which is otherwise unreachable through ordinary install inputs because git transports do not preserve FIFOs and tarball transports cannot carry FIFO entries through standard archive formats. |
+| `LOOPX_TEST_AUTOINSTALL_FAULT` | `gitignore-replace-with-socket:<workflow-name>[,<workflow-name>…]` | During the post-commit auto-install pass for the named workflow(s), immediately **after** the commit phase has placed any source `.gitignore` content and **before** the per-workflow safeguard `lstat`, replace `.loopx/<workflow-name>/.gitignore` (or create the path if it does not exist) with a Unix-domain socket (e.g., via `bind(2)` on an `AF_UNIX` socket bound at the path) so that the safeguard's `lstat` observes a socket entry. Multiple values combine semicolon-separated with the other `LOOPX_TEST_AUTOINSTALL_FAULT` faults. This enables deterministic coverage of T-INST-112j — the socket branch of SPEC 10.10's non-regular `.gitignore` enumeration — which is otherwise unreachable through ordinary install inputs (sockets, like FIFOs, are not preserved through git or tarball transports). The seam may keep the socket bound through the safeguard `lstat` and unbind it after the test asserts on the entry's persistence; whether the seam closes the socket immediately after creating the on-disk entry is implementation-defined as long as the entry itself is observable as a socket via `lstat` at the moment the safeguard runs. |
+| `LOOPX_TEST_AUTOINSTALL_FAULT` | `gitignore-make-unreadable:<workflow-name>[,<workflow-name>…]` | During the post-commit auto-install pass for the named workflow(s), immediately **after** the commit phase has placed any source `.gitignore` content (per SPEC 10.11 materialization) and **before** the per-workflow safeguard `lstat`, `chmod` `.loopx/<workflow-name>/.gitignore` to mode `000` — but **only when the on-disk entry is a regular file** (the seam is a no-op when the entry is absent or non-regular, so it composes safely with the `gitignore-replace-with-symlink:` / `-fifo:` / `-socket:` seams without colliding on the same workflow name). Multiple values combine semicolon-separated with the other `LOOPX_TEST_AUTOINSTALL_FAULT` faults (e.g., `gitignore-make-unreadable:alpha;npm-spawn-fail:beta`). This enables deterministic coverage of T-INST-112k — the SPEC 10.10 regular-file branch's "loopx does not read, parse, validate, append to, or inspect the file's contents or **permissions**" clause — which is otherwise unreachable through ordinary install inputs (producing a committed regular `.gitignore` with mode `000` requires either tarball install with mode preservation through the staging-then-commit pipeline, which SPEC 10.7 does not require, or post-commit chmod after the file lands; without the seam the test is environment-sensitive and unreachable under `process.getuid() === 0`). **Mode-restoration responsibility.** The seam **does not restore** the file's mode bits — loopx leaves the on-disk `.gitignore` at mode `000` when its own auto-install pass completes, so that T-INST-112k can assert post-run that the mode bits remain `000` (proving loopx never chmod'd the file readable in order to inspect its contents or permissions). The test harness is responsible for restoring the file mode after its own assertions complete: T-INST-112k's `afterEach` (or post-assertion teardown) must `chmod` the file back to a readable value before fixture-cleanup logic attempts to read or remove it, otherwise fixture cleanup will fail with `EACCES` under `process.getuid() !== 0`. This split — loopx leaves mode `000`, harness restores in `afterEach` — is the cleanest division: it lets the test assert directly on the post-run on-disk mode bits without racing an implementation-side restore, while keeping fixture cleanup reliable across CI environments. |
+
+These variables are only checked when `NODE_ENV=test` to prevent accidental use in production. Like the function seams above, they are not part of the public API and may change between versions without a semver bump.
 
-This variable is only checked when `NODE_ENV=test` to prevent accidental use in production. Like the function seams above, this is not part of the public API and may change between versions.
+**Tmpdir creation fault injection (test-only env-var seam, non-public, not part of SPEC conformance):**
+
+The tmpdir-creation sub-step coverage tests (T-TMP-12d, T-TMP-12e) need to deterministically force `mkdtemp` to succeed while a subsequent sub-step of SPEC 7.4's creation order (identity capture or mode securing) fails. Black-box reproduction is unreliable because the same-process owner is performing the operation on a directory it just created and still has read permission on (so `stat` won't fail), and the same process also sets the directory's mode (so `chmod` won't fail). The test suite assumes the implementation honors the following test-only environment variable:
+
+| Variable | Values | Behavior |
+|----------|--------|----------|
+| `LOOPX_TEST_TMPDIR_FAULT` | `identity-capture-fail` | After `mkdtemp` succeeds during `LOOPX_TMPDIR` creation (SPEC 7.4 sub-step 1), simulate a failure of the identity-capture stat (sub-step 2) — reported as `EACCES`. The implementation observes the simulated failure at the same point an actual `stat` failure would be observed, so the SPEC 7.4 "single non-recursive `rmdir`" cleanup path runs on the partial directory created by `mkdtemp`. This enables deterministic coverage of T-TMP-12d. |
+| `LOOPX_TEST_TMPDIR_FAULT` | `identity-capture-fail-rmdir-fail` | Compound fault: both identity capture (SPEC 7.4 sub-step 2) and the subsequent single non-recursive `rmdir` on the partial directory fail with `EACCES`. The identity-capture failure observes at the same point as the `identity-capture-fail` value above, so loopx enters the SPEC 7.4 "single non-recursive `rmdir`" creation-failure cleanup path; the `rmdir` then itself observes a simulated `EACCES`. This enables deterministic coverage of T-TMP-12d2 — SPEC 7.4's "If `rmdir` fails, loopx emits a single stderr warning and leaves the path in place" branch on the creation-failure-cleanup-failure axis, which is otherwise unreachable because a same-user-owned empty directory cannot be reliably made un-`rmdir`-able through ordinary file-system inputs. |
+| `LOOPX_TEST_TMPDIR_FAULT` | `mode-secure-fail` | After `mkdtemp` and identity capture both succeed, simulate a failure of mode-securing (sub-step 3) — reported as `EACCES`. The implementation observes the simulated failure at the same point an actual `chmod` / mode-verification failure would be observed, so the SPEC 7.4 "full identity-fingerprint cleanup-safety routine" runs on the partial directory. This enables deterministic coverage of T-TMP-12e. **Combined with `LOOPX_TEST_CLEANUP_FAULT`.** `LOOPX_TEST_CLEANUP_FAULT` applies to the cleanup-safety routine regardless of whether it was invoked from a normal terminal-cleanup path or from creation-failure handling, so when set in the same run as `mode-secure-fail` the cleanup-safety routine invoked under `mode-secure-fail` observes the configured cleanup-failure when its dispatch reaches the corresponding rule. **Reachability of each cleanup-fault under `mode-secure-fail`:** `LOOPX_TEST_CLEANUP_FAULT=lstat-fail` is reachable — the top-level `lstat` is the first step of the cleanup-safety routine and runs unconditionally, so the seam fires (used by T-TMP-12e3). `LOOPX_TEST_CLEANUP_FAULT=recursive-remove-fail` is reachable — the partial directory's identity matches the recorded fingerprint (loopx just `mkdtemp`'d it and captured its identity in sub-step 2), so dispatch reaches rule 4 and the recursive-remove proceeds (used by T-TMP-12e2). `LOOPX_TEST_CLEANUP_FAULT=symlink-unlink-fail` is **not** reachable in this composition — the partial tmpdir is the directory created by `mkdtemp` in sub-step 1, never a symlink, so cleanup-safety dispatch never reaches rule 2 and the seam is a no-op; deterministic coverage of the symlink-unlink-fail branch within creation-failure handling would require a separate seam that swaps the partial directory for a symlink between sub-step 2 and the cleanup-safety dispatch, which is not provided. |
+
+Multiple values combine semicolon-separated, but only one fault per run is meaningful (the implementation reaches at most one of the two failure points before aborting tmpdir creation). This variable is only honored when `NODE_ENV=test`. Like the install-fault seams above, it is not part of the public API.
+
+**Cleanup fault injection (test-only env-var seam, non-public, not part of SPEC conformance):**
+
+SPEC 7.4 specifies three cleanup-failure branches that black-box tests cannot reliably reproduce on a same-user-owned directory under POSIX semantics: (1) the top-level `lstat` returning a non-ENOENT failure, (2) the rule-2 symlink `unlink` failing, and (3) the rule-4 recursive removal failing on an identity-matched directory. The test suite assumes the implementation honors the following test-only environment variable:
+
+| Variable | Values | Behavior |
+|----------|--------|----------|
+| `LOOPX_TEST_CLEANUP_FAULT` | `lstat-fail` | During cleanup of `LOOPX_TMPDIR`, simulate the top-level `lstat` returning a non-ENOENT failure (reported as `EACCES`). The cleanup routine observes the simulated failure at the same point an actual `lstat` failure would be observed, so the SPEC 7.4 "single stderr warning, no further changes" path runs. This enables deterministic coverage of T-TMP-40. |
+| `LOOPX_TEST_CLEANUP_FAULT` | `symlink-unlink-fail` | During cleanup of `LOOPX_TMPDIR` when the dispatch decided the path is a symlink (per SPEC 7.4 cleanup-safety rule 2), simulate the `unlink` call failing with `EACCES`. The cleanup routine observes the simulated failure at the same point an actual `unlink` failure would be observed, so the SPEC 7.4 "single stderr warning, no further changes" path runs. The seam fires only when the dispatch reached rule 2 — for non-symlink paths the seam is a no-op. This enables deterministic coverage of T-TMP-41. |
+| `LOOPX_TEST_CLEANUP_FAULT` | `recursive-remove-fail` | During cleanup of `LOOPX_TMPDIR` when the dispatch decided the path is an identity-matched directory (per SPEC 7.4 cleanup-safety rule 4), simulate the recursive removal failing with `EACCES`. The exact failure point within the recursive walk is implementation-defined (e.g., a synthetic failure at the first nested `unlink`, or at the top-level `rmdir` that closes out the walk); the seam guarantees the cleanup routine observes a failure on the recursive-remove path in the same way an actual recursive-remove failure would surface. The seam fires only when the dispatch reached rule 4 — for other paths the seam is a no-op. This enables deterministic coverage of T-TMP-42. The seam applies whenever the cleanup-safety routine is invoked, regardless of whether the invocation comes from a normal terminal cleanup path (T-TMP-42) or from the SPEC 7.4 creation-failure handling path under `LOOPX_TEST_TMPDIR_FAULT=mode-secure-fail` (T-TMP-12e2). |
+
+Multiple values combine semicolon-separated, but only one cleanup fault per run is meaningful (the dispatch reaches at most one of the three failure points for any given cleanup invocation). This variable is only honored when `NODE_ENV=test`.
+
+**Pre-iteration sentinel stderr marker (test-only, non-public, not part of SPEC conformance):**
+
+The CLI pre-iteration signal-wins tests (T-SIG-20, T-SIG-20a, T-SIG-21, T-SIG-22, T-SIG-23, T-SIG-24, T-SIG-25, T-SIG-27, T-SIG-28) need to synchronize signal delivery with the narrow window between the CLI's pre-iteration signal-handler installation and the first child spawn. To avoid relying on fragile real-time delays or fixture-triggered blocking `opendir`s, the test suite assumes loopx emits an implementation-defined sentinel line to stderr at pre-iteration start — for example `loopx: pre-iteration-begin` — immediately after installing its pre-iteration signal handlers and before starting discovery, env-file loading, target resolution, or tmpdir creation. The harness uses `waitForStderr(<sentinel>)` to observe the line and then sends SIGINT / SIGTERM during the remaining pre-iteration window.
+
+**Sentinel gate.** The sentinel must be **opt-in via a dedicated env var** — `LOOPX_TEST_PREITERATION_SENTINEL=1` (set in loopx's inherited environment by the harness, only for the pre-iteration signal-wins tests listed above). It must **not** be enabled by `NODE_ENV=test` alone, because Vitest sets `NODE_ENV=test` for every test in the suite and many tests assert empty / no-warning stderr — emitting the sentinel under `NODE_ENV=test` alone would leak the marker line into every test's stderr capture and break clean-stderr assertions. The dedicated env var is opt-in per-test, so only the pre-iteration signal-wins tests opt in. The other test-only seams in this section (`LOOPX_TEST_INSTALL_FAULT`, `LOOPX_TEST_AUTOINSTALL_FAULT`) remain `NODE_ENV=test`-gated because they alter behavior only when their value is set; the sentinel, by contrast, is purely additive stderr output that affects every gated run, so it requires the stricter dedicated-flag gate.
+
+The sentinel's exact text is implementation-defined but must be **parent-discoverable** without relying on reading the child's `process.env` from the parent (the parent test process does not observe mutations the child makes to its own `process.env`). The harness uses, in order of preference:
+
+- **(a) Fixed sentinel string under the dedicated flag.** The implementation commits to a fixed sentinel string emitted whenever `LOOPX_TEST_PREITERATION_SENTINEL=1` is set in loopx's inherited environment (and `NODE_ENV=test`, as a defense-in-depth gate against accidental production opt-in). The fixed string is documented in the implementation's test-harness README. The harness hard-codes the same fixed string as the `waitForStderr(...)` argument. This is the preferred discovery path because no additional process is spawned.
+- **(b) Internal test-only exported constant.** The implementation exports the sentinel text as a package-internal constant (for example, on the `loopx/internal` subpath described in the "pure-function exports" table above). The harness imports the constant directly from the built package and uses its value as the `waitForStderr(...)` argument. Discovery does not require the env var; emission still does.
+- **(c) Dedicated test-harness env-dump path.** The implementation provides a test-only entry point (a subcommand, flag, or binary) that, when invoked under `NODE_ENV=test` and `LOOPX_TEST_PREITERATION_SENTINEL=1`, prints the sentinel text to its own stdout and exits 0 without running the loop. The harness invokes this preflight once, captures stdout, and reuses the result across pre-iteration signal tests. Crucially, the harness observes the sentinel from the child's **stdout** (or the exported constant), not from `process.env`.
+
+Paths (a), (b), and (c) are functionally equivalent for the harness; each avoids hard-coding an implementation-specific string into the test files while remaining parent-observable. If an implementation prefers none of the above, the harness falls back to a short real-time delay before signaling, at the cost of increased flakiness.
+
+- The sentinel is only emitted when **both** `NODE_ENV=test` **and** `LOOPX_TEST_PREITERATION_SENTINEL=1` are set in loopx's inherited environment; production builds and the rest of the test suite do not see it. The pre-iteration signal-wins tests listed above are the only callers that set the dedicated flag; every other test (including the rest of the signal block, the tmpdir block, and the env-file block) leaves it unset and observes clean stderr unaffected by the sentinel.
+- The sentinel is **not** a SPEC requirement — a SPEC-conforming implementation without this marker still satisfies SPEC.md. Tests that depend on the marker remain tagged `@flaky-retry(3)` as a fallback for environments where the sentinel is unavailable or where harness timing drifts; without the sentinel they can fall back to a short real-time delay before signaling, at the cost of increased flakiness.
+
+**Auto-install pause sentinel (test-only env-var seam, non-public, not part of SPEC conformance):**
+
+The auto-install no-active-child signal-window tests (T-INST-116h, T-INST-116i, T-INST-116j, T-INST-116k) need to deliver SIGINT / SIGTERM during one of four narrow windows in the post-commit auto-install pass when no `npm install` child is currently active: (1) **between sequential workflows** (after one workflow's auto-install processing has fully completed and before the next workflow's safeguard begins); (2) **during `.gitignore` safeguard work before spawning npm** (after the safeguard `lstat` dispatch decides to synthesize / accept the existing `.gitignore` and before the spawn call); (3) **after one npm child exits and before the next workflow begins processing** (the gap between the previous workflow's `npm install` completing and the next workflow's safeguard `lstat`); and (4) **after a `.gitignore` safeguard failure but before the next workflow** (the safeguard short-circuit path that records the failure in the aggregate report and skips that workflow's `npm install`). These windows are sub-millisecond on a healthy host and cannot be deterministically targeted via real-time delays. SPEC 10.10 specifies that auto-install runs "sequentially in an implementation-defined order" and explicitly notes the cross-workflow order is not an external conformance contract — an implementation that processes a multi-workflow source in any deterministic order is conforming. Tests that need to target a specific window therefore cannot hard-code a workflow name (e.g., `between-workflows:beta`) without baking in an unspecified ordering; instead the seam exposes **ordinal** window values (e.g., `between-workflows-after-first`) that resolve to "whichever workflow loopx happens to process first in its implementation-defined auto-install order," and emits a parent-observable marker file naming that workflow so the test can assert on the observed processed/current/remaining sets rather than on hard-coded names. The test suite assumes the implementation honors the following test-only environment variable:
+
+| Variable | Values | Behavior |
+|----------|--------|----------|
+| `LOOPX_TEST_AUTOINSTALL_PAUSE` | `<window>` (ordinal form) **or** `<window>:<workflow-name>` (name-targeted form) | During the post-commit auto-install pass, when loopx reaches the named window, pause execution for a bounded interval (≥ 2 seconds and ≤ 10 seconds — long enough for the harness to deliver a signal, short enough to bound test runtime if the harness fails to deliver one) and then resume. **Recognized ordinal window values** (do not take a workflow-name suffix; resolve to "whichever workflow is at the named position in the implementation's auto-install order"): `between-workflows-after-first` (just after the *first* workflow's auto-install processing has fully completed, regardless of which workflow that was, and before any further workflow's safeguard begins), `pre-spawn-first` (during `.gitignore` safeguard work for the *first* workflow, after the safeguard dispatch decides what to do and before the `spawn("npm", …)` call), `post-exit-first` (just after loopx has observed the *first* workflow's `npm install` child exit **and recorded that workflow's auto-install terminal outcome, including any non-zero-exit aggregate failure entry**, and before any further per-workflow processing begins — i.e., the accumulator already reflects the just-exited child's success or non-zero-exit failure when the pause begins), `post-safeguard-failure-first` (just after the *first* safeguard failure for any workflow has been recorded in the aggregate report and before any further per-workflow processing begins), `post-spawn-failure-first` (just after the *first* `npm install` spawn failure for any workflow — `spawn("npm", …)` rejecting before producing a child process, e.g., the SPEC 10.10 "`npm install` spawn failure (most commonly: `npm` is not on `PATH`)" branch — has been recorded in the aggregate report and before any further per-workflow processing begins; structurally distinct from `post-exit-first` (which fires after a successfully-spawned child *exits*) and `post-safeguard-failure-first` (which fires after a per-workflow safeguard short-circuit before any spawn was attempted) — under this window no npm child has run, but the per-workflow safeguard for the failing workflow already completed before the failed spawn so its `.gitignore` synthesis side effects are on disk, and the aggregate accumulator already holds an `npm-install-spawn-failure` entry for the failing workflow), and `post-aggregate-report` (just after loopx has completed / flushed the stderr write for the final auto-install aggregate failure report — flushed as far as the runtime stream API supports for the underlying handle, since stderr is commonly a pipe in tests and `fsync(2)` on a pipe is not portable — and before loopx's process exits; used by T-INST-116l to exercise the SPEC 10.10 "unless it had already been emitted" carve-out half of the signal-termination clause; the seam fires only when an aggregate report is actually emitted, i.e., when the auto-install pass accumulated at least one failure entry, and is a no-op on a clean / no-failure auto-install pass). **Recognized name-targeted window values** (require a workflow-name suffix; useful for tests that compose with name-targeted FAULT seams or that otherwise need to pin the pause to a specific workflow without depending on the implementation-defined auto-install order — typically only sensible when a single-workflow source is used or when the targeted workflow is guaranteed to exist regardless of order): `between-workflows:<workflow-name>` (just after the previous workflow's auto-install processing completed and before the named workflow's safeguard begins; the named workflow is the *upcoming* workflow), `pre-spawn:<workflow-name>` (during `.gitignore` safeguard work for the named workflow, after the safeguard dispatch decides what to do and before the `spawn("npm", …)` call), `post-exit:<workflow-name>` (just after loopx has observed the named workflow's `npm install` child exit **and recorded that workflow's auto-install terminal outcome, including any non-zero-exit aggregate failure entry**, and before any further per-workflow processing for the next workflow begins — i.e., the accumulator already reflects the just-exited child's success or non-zero-exit failure when the pause begins; the named workflow is the *just-completed* workflow), `post-safeguard-failure:<workflow-name>` (just after the safeguard failure for the named workflow has been recorded in the aggregate report and before any further per-workflow processing for the next workflow begins; the named workflow is the workflow whose safeguard *just failed*), and `post-spawn-failure:<workflow-name>` (just after the named workflow's `npm install` spawn failure has been recorded in the aggregate report and before any further per-workflow processing for the next workflow begins; the named workflow is the workflow whose spawn *just failed*). When the harness delivers SIGINT / SIGTERM during the pause, loopx observes the signal at that point in the auto-install state machine; when no signal arrives within the bounded interval, loopx resumes normally and the test reports a harness timing failure. Only one window value is honored per run; if the value is malformed (unknown window name, missing `:` for name-targeted forms, missing workflow name for name-targeted forms), the seam is a no-op. The bounded resume-after-timeout behavior is essential: without it, a harness bug or a lost signal could deadlock the run indefinitely. **Parent-observable pause marker (required).** The companion environment variable `LOOPX_TEST_AUTOINSTALL_PAUSE_MARKER` (also gated on `NODE_ENV=test`) names an absolute file path; when set together with `LOOPX_TEST_AUTOINSTALL_PAUSE`, loopx writes a UTF-8 JSON marker file at that absolute path **immediately on entry to the pause and before the bounded delay begins**, then `fsync`s and closes the file before starting the delay timer. The harness must place this path **outside** any directory loopx may clean up (in particular, outside `$LOOPX_TMPDIR`) so the marker survives loopx's exit for post-run reads. The harness sets `LOOPX_TEST_AUTOINSTALL_PAUSE_MARKER` to a path under the test's own temp directory. The marker contents have the shape `{"window": "<resolved-window-value>", "current": "<workflow-name>", "processed": ["<workflow-name>", …], "remaining": ["<workflow-name>", …]}` where (a) `window` echoes the resolved window value (e.g., `between-workflows-after-first` or `pre-spawn:beta`); (b) `current` is the workflow name at the seam's focal position — for `between-workflows-after-first` / `between-workflows:<name>`, the *upcoming* workflow whose safeguard would run next; for `pre-spawn-first` / `pre-spawn:<name>`, the workflow whose pre-spawn safeguard work the seam paused inside; for `post-exit-first` / `post-exit:<name>`, the workflow whose `npm install` child just exited; for `post-safeguard-failure-first` / `post-safeguard-failure:<name>`, the workflow whose safeguard just failed; for `post-spawn-failure-first` / `post-spawn-failure:<name>`, the workflow whose `npm install` spawn just failed; (c) `processed` is the array of workflow names whose full auto-install processing reached terminal state (success or recorded failure) **before** `current`'s focal point in the auto-install order, excluding `current`; and (d) `remaining` is the array of workflow names whose processing has not started at pause-entry, also excluding `current`. The union of `processed`, `[current]`, and `remaining` equals the set of workflows the auto-install pass would process in the implementation's auto-install order. **For the `post-aggregate-report` ordinal value** the per-workflow focal-position fields do not apply (all per-workflow processing has terminal-stated by the time the report is emitted), so the marker is written with `current` set to `null`, `processed` set to the full set of workflow names whose processing reached a terminal outcome (success or recorded failure) during the pass, and `remaining` set to the empty array; tests that depend on this window read only `window` and ignore the per-workflow fields. Because the bounded-delay timer starts only **after** the marker is written and `fsync`'d, a harness that polls for the marker file's existence and then signals is guaranteed to deliver the signal during the bounded delay (subject to ordinary scheduler jitter). If `LOOPX_TEST_AUTOINSTALL_PAUSE_MARKER` is unset or names a non-writable path, the seam still pauses for the bounded interval but the marker is not written; tests that depend on the marker MUST set the variable. |
+
+This variable is only honored when **both** `NODE_ENV=test` **and** the variable itself is set with a recognized window value; production builds and the rest of the test suite do not see any pause. Like the function and AUTOINSTALL_FAULT seams above, it is not part of the public API and may change between versions without a semver bump.
+
+The pause seam is purely additive (it does not change the auto-install state machine's logic, only inserts a wall-clock delay and a marker write at one named point) and is only triggered on tests that explicitly opt in via the env-var value. Other tests in the suite — including the active-child signal tests T-INST-116 through T-INST-116g — leave it unset and observe normal auto-install timing.
+
+**Terminal-trigger pause sentinel (test-only env-var seam, non-public, not part of SPEC conformance):**
+
+The cleanup-idempotence and warning-cardinality tests (T-TMP-38, T-TMP-39) and the terminal-outcome precedence tests (T-TERM-01, T-TERM-02, T-TERM-03, T-TERM-04) need to deterministically order or interleave concurrent terminal triggers — outcomes whose timing is sub-millisecond on a healthy host and cannot be reproduced via real-time delays. SPEC 7.2's "first terminal trigger observed by loopx determines the surfaced outcome among genuinely racing triggers" rule depends on **loopx's own observation order**, which black-box tests cannot pin to a specific resolution without a coordination seam. The test suite assumes the implementation honors the following test-only environment variable:
+
+| Variable | Values | Behavior |
+|----------|--------|----------|
+| `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE` | `cleanup-start` | At the entry of the `LOOPX_TMPDIR` cleanup routine — before any `lstat` / `unlink` / recursive-remove call — pause execution for a bounded interval (≥ 2 seconds, ≤ 10 seconds) and then resume. Used by T-TMP-38 (cleanup idempotence under racing terminal triggers — the harness delivers a second signal during the pause to exercise "at most one cleanup attempt"), T-TMP-39 (warning cardinality across racing terminals — same race, asserts at most one cleanup-related stderr warning), and T-TERM-03 (signal during cleanup of a prior signal — surfaced exit code reflects the *first* signal observation, not the second). |
+| `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE` | `child-exit-handler` | After a child-process exit is observed by the implementation (via `child.on("exit", …)` or equivalent) and **after** the implementation has recorded the child-exit terminal trigger as the first-observed trigger but **before** loopx dispatches the resulting terminal outcome to the surface (CLI exit code / `run` throw / `runPromise` rejection), pause for the bounded interval. Used by T-TERM-01 to deterministically pin the child-exit trigger as first-observed: the harness fires a competing abort during the post-observation pause; on resume, loopx must surface the child-exit outcome (because it was observed first), not the abort error (which arrived later). |
+| `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE` | `abort-listener` | After the captured `AbortSignal`'s abort listener fires and **after** the implementation has recorded the abort as the first-observed terminal trigger but **before** loopx dispatches the abort outcome, pause for the bounded interval. Used by T-TERM-02 to pin the abort trigger as first-observed: the harness invokes `.return()` / `.throw()` (the competing trigger) during the post-observation pause; on resume, loopx must surface the abort outcome (first-observed), not a `.return()` / `.throw()` settlement. |
+| `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE` | `child-spawn-failure` | After a `spawn` rejection is observed by the implementation and **after** the implementation has recorded the spawn-failure as the first-observed terminal trigger but **before** loopx dispatches the spawn-failure outcome, pause for the bounded interval. Used by T-TERM-04 variant a to pin the spawn-failure trigger as first-observed: the harness fires a competing abort during the pause; on resume, loopx must surface the spawn-failure outcome, not the abort error. |
+| `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE` | `child-spawn-attempt` | After loopx has decided to spawn a child for the next iteration and has begun the spawn attempt (e.g., entered the `child_process.spawn` / equivalent runtime call path) but **before** loopx has observed the spawn outcome (success → child-exit pathway, or failure → spawn-failure trigger), pause for the bounded interval. The seam fires only on the spawn-attempt path (not on the post-observation paths covered by `child-exit-handler` and `child-spawn-failure`). Used by T-TERM-04 variant b to deterministically separate the spawn-attempt window from competing abort observation: the harness configures a fixture whose spawn will fail (e.g., NUL-in-`RunOptions.env` per T-API-57), then fires `c.abort()` during the pause. Because the abort is delivered while loopx is paused mid-spawn-attempt and **before** loopx has observed the spawn outcome, on resume loopx's abort-listener observes the abort first and the spawn-failure later. The surfaced outcome must reflect the abort (first-observed), not the spawn failure. Without this seam, T-TERM-04 variant b cannot deterministically distinguish the residual "first-observed wins among genuinely racing triggers" rule (SPEC 7.2) from the explicit "abort wins over pre-iteration failures" rule (covered separately by T-API-65–65o), because abort delivered before the spawn attempt begins pre-empts the spawn entirely under the explicit precedence rule. |
+| `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE` | `consumer-return-observed` | After loopx's consumer-cancellation tracking observes a mid-loop `gen.return(value)` call (post-first-`next()`) and **after** the implementation has recorded the `.return()` as the first-observed terminal trigger but **before** loopx dispatches the resulting clean settlement, pause for the bounded interval. The seam fires only on mid-loop `.return()` (not on the pre-first-`next()` carve-out, which never enters loopx's machinery; not on `.throw()`). Used by T-TERM-02 variant b to pin the `.return()` trigger as first-observed: the harness drives `gen.next()` once (entering the loop), waits for the script's "ready" marker, then calls `gen.return(undefined)`; loopx observes the `.return()` and pauses; the harness fires `c.abort()` during the pause; on resume, loopx must surface the clean `.return()` settlement (per standard async-generator semantics — first-observed trigger wins), not an abort error. |
+| `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE` | `consumer-throw-observed` | Counterpart to `consumer-return-observed` for the `.throw()` axis. After loopx observes a mid-loop `gen.throw(err)` call (post-first-`next()`) as the first-observed terminal trigger but before dispatch, pause for the bounded interval. Used by tests that need to pin `.throw()` as the first-observed trigger against a competing abort or non-zero exit, with the same parent-observable marker contract as the other window values. |
+
+When the harness delivers the second trigger (signal, abort, `.return()`, `.throw()`, or whatever competes with the first-observed) during the pause, loopx observes it *after* the first-observed trigger is already pinned; the surfaced outcome must reflect the first-observed trigger, not the late one. When no second trigger arrives within the bounded interval, loopx resumes normally and the pinned-first trigger drives the outcome (the test reports a harness timing failure if it expected a race). Only one window value is honored per run; if the value is malformed (unknown window name), the seam is a no-op. The bounded resume-after-timeout behavior is essential: without it, a harness bug or a lost trigger could deadlock the run indefinitely.
+
+**Parent-observable pause marker (required).** The companion environment variable `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE_MARKER` (also gated on `NODE_ENV=test`) names an absolute file path; when set together with `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE`, loopx writes a UTF-8 JSON marker file at that absolute path **immediately on entry to the pause and before the bounded delay begins**, then `fsync`s and closes the file before starting the delay timer. The harness must place this path **outside** any directory loopx may clean up (in particular, outside `$LOOPX_TMPDIR`) so the marker survives loopx's exit for post-run reads. The marker contents have the shape `{"window": "<resolved-window-value>"}`; additional fields may be added in future without breaking compatibility, and tests should ignore unknown fields. Because the bounded-delay timer starts only **after** the marker is written and `fsync`'d, a harness that polls for the marker file's existence and then triggers the second event is guaranteed to deliver the trigger during the bounded delay (subject to ordinary scheduler jitter). If `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE_MARKER` is unset or names a non-writable path, the seam still pauses for the bounded interval but the marker is not written; tests that depend on the marker MUST set the variable.
+
+This variable is only honored when **both** `NODE_ENV=test` **and** the variable itself is set with a recognized window value; production builds and the rest of the test suite do not see any pause. Like the auto-install pause seam above, it is not part of the public API and may change between versions without a semver bump. The pause seam is purely additive (it does not change the terminal-trigger dispatch logic, only inserts a wall-clock delay between trigger observation and outcome dispatch, and a marker write) and is only triggered on tests that explicitly opt in via the env-var value.
+
+**Cleanup-warning structured marker (test-only stderr seam, non-public, not part of SPEC conformance):**
+
+Because SPEC 7.4 leaves the cleanup-warning text implementation-defined, "exactly one cleanup-related warning" / "no cleanup-related warning" / "at most one cleanup-related warning" assertions across the suite (T-TMP-35*, T-TMP-36*, T-TMP-38*, T-TMP-40, T-TMP-41, T-TMP-42, T-TMP-42a, T-TMP-42b, T-TMP-42c, T-TERM-03, T-INST-116l, etc.) need an **implementation-neutral detection predicate** rather than a fixed text match. Many of these tests run on **mixed-stderr terminals** (creation-failure errors alongside cleanup warnings — T-TMP-12d2 / T-TMP-12e2 / T-TMP-12e3; script-failure terminals — T-TMP-35c / T-TMP-35d / T-TMP-35e / T-TMP-42a; abort terminals — T-TMP-42b; signal terminals — T-TMP-35f / T-TMP-42c; racing-trigger warning-cardinality — T-TMP-38 / T-TMP-39 / T-TMP-38a / T-TMP-38a2 / T-TMP-38b / T-TMP-38c / T-TMP-38d / T-TMP-38d2 / T-TMP-38e), where the non-cleanup stderr is **not** a caller-controlled fixture marker but an implementation-defined loopx-emitted error whose text varies between conforming implementations. Inferred-residue counting (subtract known fixture markers, count what's left) cannot reliably distinguish a cleanup warning from an implementation-defined creation-failure or script-failure error in those cases. The harness therefore requires a **structured cleanup-warning marker** as a test-only seam.
+
+When `NODE_ENV=test`, every cleanup-warning emission also emits a fixed structured marker line to stderr alongside the human-readable warning text. The marker is purely additive (does not change SPEC-conformant warning emission) and is gated on `NODE_ENV=test` so production builds never emit it. The marker line follows the shape `LOOPX_TEST_CLEANUP_WARNING\t<implementation-defined-payload>` — a fixed leading prefix `LOOPX_TEST_CLEANUP_WARNING` followed by a tab and an implementation-defined remainder (e.g., a JSON payload, a path mention, or any other diagnostic data the implementation finds useful for test-time inspection). The harness counts only lines beginning with `LOOPX_TEST_CLEANUP_WARNING\t` as cleanup-warning emissions; the human-readable warning text alongside the marker is not part of the cardinality count.
+
+**Required, not optional.** Unlike the pre-iteration sentinel above (which has fallback predicates a/b/c with documented flakiness), the cleanup-warning marker is **required** for cleanup-warning cardinality tests because mixed-stderr terminals offer no caller-controlled disambiguation. An implementation that does not emit the marker under `NODE_ENV=test` cannot reliably pass cleanup-warning cardinality tests. The marker is **not part of the public SPEC contract** — like the rest of the seams in this section (`LOOPX_TEST_INSTALL_FAULT`, `LOOPX_TEST_TMPDIR_FAULT`, `LOOPX_TEST_CLEANUP_FAULT`, `LOOPX_TEST_AUTOINSTALL_PAUSE`, `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE`, `LOOPX_TEST_PREITERATION_SENTINEL`), it is a test-only harness contract that may change between versions without a semver bump.
+
+**Discovery.** The fixed prefix `LOOPX_TEST_CLEANUP_WARNING` is documented in the implementation's test-harness README and hard-coded into the harness. As an alternative to a hard-coded prefix, the implementation may export the prefix as a package-internal constant on a `loopx/internal` subpath (analogous to the pre-iteration sentinel paths above), in which case the harness imports the constant directly. The exact discovery path is implementation-defined; the harness's only requirement is parent-discoverable, parent-observable marker text.
+
+**Negative assertions.** The negative form ("no cleanup-related warning" — used by T-TMP-12a "no path exists, so no cleanup is needed" and similar zero-warning paths) inverts the predicate: assert that zero `LOOPX_TEST_CLEANUP_WARNING\t…` lines appear on stderr.
+
+**Disambiguation from non-cleanup stderr.** Because the marker is keyed on a fixed prefix, the harness can disambiguate the cleanup warning from other stderr categories in the same run regardless of the implementation-defined wording of either: a creation-failure error in T-TMP-12d2 (loopx-emitted, implementation-defined text, no marker prefix) is not counted as a cleanup warning even when it appears alongside one (with the marker prefix). The script-failure marker line `SCRIPT-FAILURE-MARKER-T-TMP-35C` (caller-controlled) is also not counted because it does not carry the cleanup-warning prefix. Tests no longer need to specify "subtract known fixture markers, then count residue" — they simply count `LOOPX_TEST_CLEANUP_WARNING\t…` lines.
 
 ---
 
@@ -110,7 +210,7 @@ tests/
     types.test.ts              Compile-time type surface verification
   helpers/
     cli.ts                     CLI spawning utilities (runCLI, runCLIWithSignal)
-    api-driver.ts              Programmatic API driver (runAPIDriver)
+    api-driver.ts              Programmatic API driver (runAPIDriver, runAPIDriverLive)
     fixtures.ts                Temp dir, workflow, script, and project creation
     servers.ts                 Local HTTP & git servers, git URL rewriting
     env.ts                     Env file creation, global config, isolated home
@@ -198,9 +298,93 @@ const result = await runAPIDriver("bun", `
 const outputs = JSON.parse(result.stdout);
 ```
 
-#### `runCLIWithSignal(args, options): Promise<CLIResult>`
+#### `runAPIDriverLive(runtime, code, options?): APIDriverHandle`
+
+Like `runAPIDriver`, but **does not return a settled `Promise`** — it returns a live driver-process handle so the test can observe mid-run events (stderr markers, stdout markers, the driver's PID) and deliver out-of-band signals or coordination messages while the driver script (and its loopx loop) is still executing. A settled promise is incompatible with mid-run synchronization patterns required by several programmatic-API signal / cancellation tests (T-API-10d / 10e / 10f / 10g / 10h, the `runPromise` signal counterparts T-API-10d-promise / T-API-10e-promise, and other tests where the harness must `waitForStderr("ready")` and read a PID from a marker before calling `c.abort()` / `gen.return()` / etc.). Without this helper, those tests would have to embed all synchronization inside the driver script itself, which prevents the harness from reading the child's stderr or PID at the synchronization point.
+
+This is the programmatic-API counterpart to `runCLIWithSignal` for CLI tests.
+
+```typescript
+interface APIDriverHandle {
+  /** Send a signal to the driver process (which forwards into loopx via standard runtime signal disposition). Returns once the signal has been delivered from the harness. */
+  sendSignal(signal: "SIGINT" | "SIGTERM" | "SIGKILL" | NodeJS.Signals): void;
+  /** Resolves when the driver's stderr emits a line matching `pattern`. Rejects on timeout or driver exit. The driver's stderr captures script stderr (per Spec 9.3 stderr passthrough) and any harness-instrumentation lines the driver script writes itself. */
+  waitForStderr(pattern: string | RegExp, options?: { timeoutMs?: number }): Promise<void>;
+  /** Resolves when the driver's stdout emits a line matching `pattern`. Rejects on timeout or driver exit. The driver's stdout is where the test driver script prints its own JSON results (e.g., yielded outputs) — useful for tests that need to observe partial output before the loop completes. */
+  waitForStdout(pattern: string | RegExp, options?: { timeoutMs?: number }): Promise<void>;
+  /** Resolves with the final `{ stdout, stderr, exitCode }` once the driver exits. Idempotent. */
+  waitForExit(): Promise<{ stdout: string; stderr: string; exitCode: number }>;
+  /** The driver child's process ID (available once spawn succeeds). */
+  pid: number;
+}
+```
+
+The driver script itself is responsible for surfacing per-iteration markers the harness needs (e.g., emitting `"ready"` to stderr after `gen.next()` yields, or printing the active child's PID via a fixture-supplied marker file). The harness reads markers via `waitForStderr` / `waitForStdout` or via filesystem polling on a fixture-written marker file, then triggers the next coordination step (e.g., `sendSignal`, or a follow-up file-system mutation).
 
-Like `runCLI`, but also returns a `sendSignal(signal)` function and a `waitForStderr(pattern)` function so the test can send SIGINT/SIGTERM at a controlled point during execution.
+Typical usage:
+
+```typescript
+// T-API-10d-style: aborting an active-child run via runPromise().
+// The driver script awaits runPromise() but is structured so the abort can
+// be delivered from outside the driver process.
+const handle = runAPIDriverLive("node", `
+  import { runPromise } from "loopx";
+  // The fixture's child script writes its PID to a marker file and "ready"
+  // to stderr; the harness reads the marker, then sends a signal to *this*
+  // driver process to trigger the abort.
+  process.on("SIGUSR1", () => globalThis.__loopxAbortController?.abort());
+  globalThis.__loopxAbortController = new AbortController();
+  try {
+    const outputs = await runPromise("ralph", {
+      cwd: "${project.dir}",
+      signal: globalThis.__loopxAbortController.signal,
+    });
+    console.log(JSON.stringify({ ok: true, outputs }));
+  } catch (e) {
+    console.log(JSON.stringify({ ok: false, error: String(e) }));
+  }
+`, { cwd: project.dir });
+
+await handle.waitForStderr("ready");
+const childPid = readPidMarker();          // fixture-supplied marker
+handle.sendSignal("SIGUSR1");              // triggers c.abort() inside driver
+const { stdout, exitCode } = await handle.waitForExit();
+const result = JSON.parse(stdout);
+expect(result.ok).toBe(false);
+expect(result.error).toMatch(/abort/i);
+expect(processIsAlive(childPid)).toBe(false);
+```
+
+Tests may alternatively choose to deliver coordination via a file-system sentinel the driver script polls, or via a per-driver-process IPC channel — the helper is agnostic to the in-driver synchronization mechanism, but it must expose `waitForStderr` / `waitForStdout` / `waitForExit` / `pid` / `sendSignal` so the harness can observe child markers and trigger out-of-band actions before the driver settles.
+
+#### `runCLIWithSignal(args, options): CLIProcessHandle`
+
+Like `runCLI`, but **does not return a settled `Promise<CLIResult>`** — it returns a live process handle so the test can observe mid-run events (stderr markers, child state) and send signals while loopx is still executing. A settled `Promise<CLIResult>` is incompatible with mid-run signaling, which is why this helper exposes a handle object instead of a promise.
+
+```typescript
+interface CLIProcessHandle {
+  /** Send a signal to the loopx process. Returns once the signal has been delivered from the harness. */
+  sendSignal(signal: "SIGINT" | "SIGTERM" | "SIGKILL" | NodeJS.Signals): void;
+  /** Resolves when stderr emits a line matching `pattern` (string substring or RegExp). Rejects on timeout or child exit. */
+  waitForStderr(pattern: string | RegExp, options?: { timeoutMs?: number }): Promise<void>;
+  /** Resolves when stdout emits a line matching `pattern` (string substring or RegExp). Rejects on timeout or child exit. Used by streaming-passthrough tests (e.g., T-INST-119a) to observe bytes before the child exits. */
+  waitForStdout(pattern: string | RegExp, options?: { timeoutMs?: number }): Promise<void>;
+  /** Resolves with the final `CLIResult` once loopx exits. Idempotent — calling twice returns the same settlement. */
+  waitForExit(): Promise<CLIResult>;
+  /** The child's process ID (available once spawn succeeds). */
+  pid: number;
+}
+```
+
+Typical usage:
+
+```typescript
+const handle = runCLIWithSignal(["run", "ralph"], { cwd: project.dir });
+await handle.waitForStderr("ready");
+handle.sendSignal("SIGINT");
+const result = await handle.waitForExit();
+expect(result.exitCode).toBe(130);
+```
 
 #### `createEnvFile(path, vars): void`
 
@@ -253,6 +437,251 @@ await withGitURLRewrite({
 });
 ```
 
+#### `withFakeNpm(options, fn): Promise<FakeNpmResult>`
+
+Creates a throw-away directory containing a shim executable named `npm` and prepends that directory to `PATH` for the duration of `fn`. The shim is used by Spec 10.10 auto-install tests to make `npm install` deterministic and observable without depending on real npm. Options control the shim's behavior:
+
+```typescript
+interface FakeNpmOptions {
+  // Default exit code the shim returns. 0 = success; non-zero = npm install failure.
+  exitCode?: number;                    // default 0
+  // Per-workflow exit-code overrides, keyed by the workflow name (derived from
+  // the shim's cwd basename under `.loopx/`). Example: `{ beta: 1 }` makes
+  // `npm install` exit non-zero only for `.loopx/beta/`, regardless of the
+  // auto-install-order position of `beta` among the processed workflows. Workflows
+  // not listed fall back to `exitCode`. Used by T-INST-114 (fail on a single
+  // named workflow in a multi-workflow install). Workflow-name keying rather
+  // than invocation-order keying is required because SPEC 10.10 explicitly
+  // makes the cross-workflow auto-install order implementation-defined and
+  // not an external conformance contract — so an invocation-position key
+  // (`{ 2: 1 }`) would tacitly bake an unspecified ordering assumption into
+  // the test.
+  exitCodeByWorkflow?: Record<string, number>;
+  // If true, the helper constrains PATH for `fn` so `npm` resolution fails
+  // with ENOENT and no shim is created. Used by T-INST-114a for the
+  // all-invocations spawn-failure case.
+  //
+  // Note on per-invocation spawn failure (T-INST-114b): a black-box fake `npm`
+  // shim cannot reliably make only a specific `spawn("npm")` call fail with
+  // ENOENT while other calls succeed, because once a shim process starts, the
+  // spawn itself has already succeeded. Per-workflow spawn-failure coverage is
+  // driven through the `LOOPX_TEST_AUTOINSTALL_FAULT=npm-spawn-fail:<workflow>`
+  // implementation seam (section 1.4), not through this helper. This field is
+  // therefore intentionally omitted from the helper; selective per-invocation
+  // spawn failure is routed through the seam instead.
+  spawnFailure?: boolean;               // default false
+  // Optional stdout/stderr the shim writes before exiting.
+  stdout?: string;
+  stderr?: string;
+  // If set (global), the shim sleeps this many seconds before exiting — used by
+  // signal-during-npm-install tests so the harness can send a signal while
+  // the child is active. Combined with the ready-protocol: the shim writes
+  // "ready" to stderr immediately on start, writes its PID to `pidFile` (if
+  // set), then sleeps. Tests that care only about "signal while the first
+  // workflow is installing, subsequent workflows must not be processed" can
+  // use `sleepSeconds` alone because the first invocation is observable
+  // regardless of which workflow it targets.
+  sleepSeconds?: number;
+  // Per-workflow sleep overrides, keyed by the workflow name (derived from the
+  // shim's cwd basename under `.loopx/`). Example: `{ alpha: 30 }` makes the
+  // shim sleep only when invoked in `.loopx/alpha/`, regardless of
+  // auto-install-order position. Workflows not listed fall back to
+  // `sleepSeconds` (or exit immediately if `sleepSeconds` is unset).
+  // Workflow-name keying avoids the same implementation-defined-ordering
+  // issue described for `exitCodeByWorkflow`.
+  sleepByWorkflow?: Record<string, number>;
+  // If set, the shim installs a Bash `trap '' <signal>` clause for each listed
+  // signal before entering the sleep, so the shim ignores those signals and
+  // stays alive past the normal termination path. Used by T-INST-116c to force
+  // the 5-second grace period + SIGKILL escalation path — the shim traps SIGTERM
+  // (and optionally SIGINT), so loopx must escalate to SIGKILL to kill the
+  // child after the grace window. This mirrors the `signal-trap-ignore` fixture
+  // in section 2.4 applied to the npm shim context.
+  trapSignals?: Array<"TERM" | "INT">;
+  // If true, the shim spawns a long-lived background grandchild process
+  // (for example `sleep 3600 &`), writes that PID to `grandchildPidFile`,
+  // writes "ready" to stderr, then waits. Used by T-INST-116e to verify
+  // that loopx forwards signals to the npm child's process group, not only
+  // to the npm shim process itself.
+  spawnGrandchild?: boolean;
+  grandchildPidFile?: string;
+  // If set, the shim writes its own PID (`$$`) to this absolute file path as
+  // part of the ready protocol — after writing "ready" to stderr and **before**
+  // any optional `sleepSeconds` wait or `exitCode` exit. The harness reads this
+  // file (after `waitForStderr("ready")` resolves, the PID file is guaranteed
+  // present) to obtain the shim PID while the shim is still alive — required
+  // by tests that observe shim liveness mid-flight (e.g., `kill -0 <pid>`,
+  // active-child signal forwarding tests T-INST-116 / 116a / 116c / 116f, the
+  // streaming-passthrough tests T-INST-119a / T-INST-119a-stderr, and any test
+  // that needs the shim PID before the per-invocation log entry has been
+  // finalized at process exit). The per-invocation log entries written via
+  // `logFile` are appended **on shim exit** (each entry includes both
+  // `startedAtMs` and `endedAtMs`), so they are not observable while the shim
+  // is still alive — `pidFile` is the canonical alive-shim PID surface. The
+  // file is written via `printf '%s' "$$" > "<pidFile>"` so the contents are
+  // exactly the PID with no trailing newline; harness consumers parse a
+  // non-negative integer. Tests that need per-workflow PID files (e.g., one
+  // PID file per multi-workflow shim invocation) supply distinct paths
+  // through their fixture setup; the helper does not generate per-workflow
+  // paths automatically.
+  pidFile?: string;
+  // Optional relative file paths (resolved against the shim's cwd) to create
+  // before the shim sleeps and/or exits. Parent directories are created as
+  // needed. Used to simulate partial `node_modules/` state that loopx must not
+  // clean up after failed or interrupted auto-install runs (T-INST-116d,
+  // T-INST-117a).
+  createFiles?: string[];
+  // Marker file path; every shim invocation appends one line of JSON
+  // describing its argv, cwd, and selected env vars (PATH, LOOPX_*, TMPDIR,
+  // ...) so the test can assert which workflows npm was invoked for, in
+  // what order, and with what environment. **The log entry is written on
+  // shim exit** — it includes both `startedAtMs` and `endedAtMs`, and is
+  // therefore not observable while the shim is still running. Tests that
+  // need the shim PID (or any other start-time field) while the shim is
+  // alive must use `pidFile` (and the stderr `"ready"` marker for
+  // synchronization), not the log file.
+  //
+  // **Signal-termination behavior (required).** "On shim exit" includes
+  // signal-induced termination by SIGINT or SIGTERM (the signals
+  // T-INST-116b / T-INST-116b2 / T-INST-116j / T-INST-116j2 etc. assert
+  // log-invocation counts against). The shim implementation must therefore
+  // install a Bash `trap` clause on `EXIT` (or equivalent) early in its
+  // preamble — before the optional `sleepSeconds` wait — that finalizes
+  // the per-invocation log entry regardless of whether the shim ran to
+  // completion or was interrupted by a signal-driven Bash exit. The trap
+  // captures `endedAtMs` at the moment of termination so the
+  // `startedAtMs <= endedAtMs` invariant holds; tests must not rely on
+  // byte-exact `endedAtMs` content under signal termination, only on the
+  // entry's existence and on the `argv` / `cwd` fields used for
+  // invocation-count and per-workflow-cwd assertions. **SIGKILL is
+  // intentionally not covered by this guarantee** (no userspace trap can
+  // run when a process is SIGKILL'd); tests in the SIGKILL-escalation
+  // path (T-INST-116c with `trapSignals: ["TERM", "INT"]` and the
+  // SIGINT-axis counterpart T-INST-116f) accordingly do **not** assert on
+  // the shim log — they assert on shim PID termination via `pidFile` +
+  // `kill -0` instead. Tests that need to assert "exactly N invocations
+  // ran before the signal" under SIGINT / SIGTERM termination read the
+  // exit-time log; tests that need mid-flight observation use `pidFile`
+  // and the stderr `"ready"` marker plus on-disk side effects (e.g.,
+  // `.gitignore` synthesis state per T-INST-116b's clause (c)/(d)) so
+  // they do not depend on the exit-time log at all.
+  logFile: string;
+  // If true, the shim records — as its very first action on startup, before
+  // any other side effect — whether `<cwd>/.gitignore` existed at the moment
+  // of spawn, plus its content if present. Used by T-INST-112 to pin down the
+  // SPEC 10.10 ordering "Immediately before spawning `npm install`, loopx
+  // checks for a top-level `.gitignore` ... If none exists, loopx creates
+  // one containing the single line `node_modules`." The shim captures
+  // `fs.existsSync('.gitignore')` and the file's content as the very first
+  // line of its Bash preamble (before stdout/stderr emission, before
+  // `createFiles` actions, before `sleepSeconds` waits). The recorded state
+  // appears on each `FakeNpmInvocation` log entry as `gitignoreAtStart`.
+  // Without this option, the per-invocation log entry omits the
+  // `gitignoreAtStart` field (existing tests are unaffected).
+  recordGitignoreAtStart?: boolean;
+}
+
+interface FakeNpmResult {
+  logFile: string;                      // same as options.logFile
+  readInvocations(): FakeNpmInvocation[]; // parsed log entries
+}
+
+interface FakeNpmInvocation {
+  argv: string[];                       // argv passed to npm
+  cwd: string;                          // shim's process.cwd()
+  env: Record<string, string>;          // selected env vars seen by shim
+  pid: number;
+  /** Wall-clock milliseconds (`Date.now()` in the shim) at which the shim
+   *  started recording its invocation, captured **before** any optional
+   *  `sleepSeconds` wait or `exitCode` exit. Used by tests that assert
+   *  sequential / non-overlapping per-workflow processing per SPEC 10.10
+   *  ("sequentially in an implementation-defined order; npm children do
+   *  not overlap") — e.g., T-INST-110 (two workflows alpha/beta both reach
+   *  the shim) and T-INST-114 (three workflows alpha/beta/gamma all reach
+   *  the shim). The recorded value is from the shim's clock, so
+   *  cross-process clock-skew is not a concern within a single install
+   *  command. */
+  startedAtMs: number;
+  /** Wall-clock milliseconds at which the shim finished and was about to
+   *  exit. Combined with `startedAtMs`, lets tests verify that two
+   *  per-workflow invocations did not overlap in wall-clock time
+   *  (`a.endedAtMs <= b.startedAtMs` or vice versa). */
+  endedAtMs: number;
+  /** Snapshot of the `.gitignore` file at the moment of spawn, captured as
+   *  the first action in the shim's preamble before any other side effect.
+   *  Present **only** when `FakeNpmOptions.recordGitignoreAtStart` is true;
+   *  omitted otherwise. `existed` is `fs.existsSync('.gitignore')` at shim
+   *  start; `content` is the file's full content as a string when `existed`
+   *  is true (UTF-8 read, no trimming), or omitted when `existed` is false.
+   *  This is the seam used by T-INST-112 to assert that loopx's `.gitignore`
+   *  safeguard ran **before** spawning `npm install` per SPEC 10.10's
+   *  "Immediately before spawning `npm install`" wording — a buggy
+   *  implementation that ran npm first and synthesized `.gitignore`
+   *  afterward would produce `existed: false` here while still leaving a
+   *  correct end-state on disk. */
+  gitignoreAtStart?: {
+    existed: boolean;
+    content?: string;
+  };
+}
+```
+
+The shim is implemented as a small Bash script (or a `tsx`-driven Node/Bun script when `npm` might need to behave differently per runtime). Tests that need both invocation recording *and* signal/ready synchronization combine `sleepSeconds` with the standard ready-protocol (`waitForStderr("ready")`) documented for the signal fixtures in section 2.4.
+
+**Raw-env recording for PWD-sensitive assertions (required).** The per-invocation log entry's `env` field records selected environment variables observed by the shim. For most variables, recording via the host shell's interpolated value (e.g., Bash `${VAR}` or Node `process.env.VAR`) yields the inherited value byte-for-byte. **The `PWD` variable is a special case under a Bash shim**: Bash rewrites its own `$PWD` on shell startup to match `getcwd(3)` whenever the inherited `PWD` does not refer to the current working directory, and because Bash exports `PWD`, the rewrite is also visible to subsequent `printenv PWD` / `env` reads of the shell's own environment. A Bash shim that logs `PWD` via `${PWD}` (or via `printenv PWD` / `env | grep PWD` after Bash has initialized) therefore records the **shell-rewritten** value, which equals the shim's own cwd (e.g., `.loopx/<workflow>/`) — not loopx's inherited `PWD` (e.g., `<project-root>`). A conforming implementation that correctly inherits loopx's `PWD` unchanged would falsely fail an assertion that compares the recorded `PWD` to loopx's inherited `PWD` byte-for-byte. The helper must therefore record `PWD` (and any other variable whose value is sensitive to shell-managed-`$PWD` semantics) via a **raw-env mechanism** that observes the process's inherited environment **before any shell-startup rewrite** — equivalently: a Node/Bun shim implementation reading `process.env.PWD` (Node and Bun do not rewrite the inherited `PWD` to `getcwd()` on startup); or, in a Bash shim, an `exec env` / `exec /usr/bin/env` invocation from the first executable line of the shim (before Bash's `cmd_init()` PWD rewrite has taken effect, captured by spawning a sub-`env` process and parsing its output) or a direct read of `/proc/self/environ` on Linux. The recommended approach is a Node/Bun shim implementation when the test's invocation log requires a faithful `PWD` field. Tests that depend on byte-for-byte `PWD` parity with loopx's inherited environment (T-INST-115 specifically) MUST use this raw-env recording path; tests that record `PWD` only as a "field present, value not asserted byte-for-byte" observation are not constrained.
+
+This helper must also be able to make `npm` resolution fail deterministically
+on hosts that already have a real `npm` installed. The all-invocations
+`spawnFailure: true` option **must** cause `spawn("npm", …)` itself to
+fail with `ENOENT` — i.e., the `spawn` call never produces a child
+process. It is implemented by **PATH control / no resolvable `npm`** (the
+helper rewrites `PATH` for the duration of `fn` so no `npm` binary is
+findable, and creates no shim file). A dispatcher-shim implementation
+that starts a process which then exits non-zero is **not** equivalent —
+that is a non-zero exit, not a spawn failure, and would defeat
+T-INST-114a's contract that the fake-npm log records zero invocations
+(the shim never started). Selective per-invocation spawn failure (e.g.,
+failing only the 2nd of three workflow installs) is **intentionally not**
+a helper option — per the `spawnFailure` field note above, that coverage
+is routed through the `LOOPX_TEST_AUTOINSTALL_FAULT=npm-spawn-fail:<workflow>`
+test-only implementation seam (section 1.4), since a black-box shim cannot
+make only a specific `spawn("npm")` call fail with ENOENT once the shim
+process has already started. Any "`spawnFailureOnInvocation`" terminology
+elsewhere should be read as referring to the seam, not to a helper option.
+
+This helper is the primary seam for Spec 10.10 auto-install coverage (`T-INST-110` block below). Without it, auto-install tests would be flaky (depending on real npm + registry availability) or impossible (`spawnFailure`, signal-during-npm-install, and `PATH`-controlled spawn behavior cannot be driven deterministically by the real `npm`).
+
+#### `withFakeGit(options, fn): Promise<FakeGitResult>`
+
+Creates a throw-away directory containing a shim executable named `git` and prepends that directory to `PATH` for the duration of `fn`. The shim wraps the **real** `git` binary (resolved from a known absolute path, e.g., `/usr/bin/git`, to avoid recursing into the shim) so that git operations still succeed against local bare repos, while every invocation is recorded to a log file for assertion. Used by Spec 10.2 git install tests that need to observe the argv `loopx` passed to `git` — most importantly T-INST-87's assertion that `loopx install` invokes `git clone` with `--depth 1`.
+
+```typescript
+interface FakeGitOptions {
+  // Marker log file; every shim invocation appends one line of JSON
+  // describing its argv, cwd, and selected env vars so the test can
+  // assert what subcommand, flags, and URL loopx passed.
+  logFile: string;
+  // Absolute path to the real git binary that the shim should exec.
+  // Defaults to `/usr/bin/git`. Tests may override for CI environments
+  // where git lives elsewhere.
+  realGitPath?: string;
+}
+
+interface FakeGitResult {
+  logFile: string;
+  readInvocations(): FakeGitInvocation[];
+}
+
+interface FakeGitInvocation {
+  argv: string[];   // full argv including the `git` program name at [0]
+  cwd: string;
+  env: Record<string, string>;
+  exitCode: number; // exit code of the real git invocation
+}
+```
+
+The shim is a thin Bash wrapper: it appends an argv/cwd/env log entry, then `exec`s the real git with the original argv. This guarantees loopx's actual git interactions still succeed (clones into staging, etc.) while the test has a black-box-visible record of `git clone --depth 1 <url> <dir>` and similar. Without this seam, "clone has only 1 commit" is observable only by post-clone `git log` inspection of the final installed workflow directory — but installed workflows do not retain the `.git/` directory after the stage-then-commit copy, so post-install `git log` is not available. Asserting on the argv loopx passed to the cloning process is the correct black-box-visible assertion.
+
 #### `forEachRuntime(fn): void`
 
 Test parameterization helper. Runs a test block once for each available runtime (Node.js, Bun). Skips a runtime if it's not installed. Example:
@@ -283,21 +712,31 @@ A catalog of reusable fixture scripts used across tests. Each is a function that
 | `sleep-then-exit(seconds)` | bash | Sleeps for `<seconds>`, then exits 0. General-purpose long-running script. For signal tests, prefer the dedicated `signal-*` fixtures which follow the ready-protocol. |
 | `write-env-to-file(varname, markerPath)` | bash | `printf '%s' "$VARNAME"` to a marker file. Uses `printf '%s'` (not `echo`) to avoid trailing newline and backslash interpretation. Observation via filesystem, not CLI stdout. |
 | `observe-env(varname, markerPath)` | ts | Writes JSON `{ "present": true, "value": "..." }` or `{ "present": false }` to a marker file using `fs.writeFileSync`. Distinguishes unset from empty string. Use instead of `write-env-to-file` when the test must differentiate between a variable being absent vs set to `""`. |
-| `write-cwd-to-file(markerPath)` | bash | `printf '%s' "$PWD"` to a marker file. Uses `printf '%s'` (not `echo`) for exact-byte safety. |
+| `write-cwd-to-file(markerPath)` | bash | `/bin/pwd -P` piped through `printf '%s'` to a marker file. Uses `/bin/pwd -P` (not `$PWD`) because Spec 6.1 explicitly declares `$PWD` non-authoritative for cwd assertions — `$PWD` is shell-maintained and inherits loopx's own `PWD`, so byte-for-byte equality between `$PWD` and the spawn cwd is not a loopx guarantee. `/bin/pwd -P` reports the kernel cwd spelling via `getcwd(3)`. |
+| `observe-cwd-ts(markerPath)` | ts | Writes `process.cwd()` to a marker file via `fs.writeFileSync`. Use for cwd assertions in JS/TS contexts where Node/Bun's `getcwd(3)`-based `process.cwd()` is authoritative. Complements the Bash `write-cwd-to-file` fixture (which uses `/bin/pwd -P`). |
+| `observe-pwd(markerPath)` | bash | `printf '%s' "${PWD:-<unset>}"` to a marker file. **Separate from `write-cwd-to-file`** — this fixture exists specifically to observe Bash's shell-managed `$PWD` variable (not the kernel cwd, and not the inherited env-map value), used by a narrow class of tests that specifically want to observe Bash's shell-level PWD. **Do not use for exact-value `PWD` passthrough assertions** — Bash may rewrite `$PWD` during shell startup under normal POSIX / Bash semantics, so byte-for-byte equality between Bash `$PWD` and a caller-supplied value is not a loopx guarantee (Spec 6.1 / 8.3 / 13). Tests that assert exact passthrough of `PWD` via the env-map tiers (T-PWD-01 / 02 / 03 / 06) use `observe-env` with variable name `PWD` instead, which reads `process.env.PWD` directly under Node / Bun and preserves the inherited value byte-for-byte. |
 | `write-value-to-file(value, markerPath)` | bash | `printf '%s' '<value>'` to a marker file. Uses `printf '%s'` (not `echo`) for exact-byte safety — avoids trailing newlines, backslash interpretation, and issues with values starting with `-`. General-purpose observation helper. |
 | `stdout-writer(payloadFile)` | ts | Reads `payloadFile` from disk and writes its contents to stdout via `process.stdout.write()`. Used for fuzz and exact-byte output tests. |
 | `ts-output(fields)` | ts | Uses `import { output } from "loopx"` to emit structured output |
 | `ts-input-echo()` | ts | Reads input(), outputs it as result |
 | `ts-import-check()` | ts | Imports from "loopx", outputs success marker |
 | `signal-ready-then-sleep(markerPath)` | bash | Writes `$$` (the script's PID) to a marker file using `printf '%s'`, then writes `"ready"` to stderr, then sleeps indefinitely. The stderr marker allows the test harness to `waitForStderr("ready")` before sending a signal, ensuring the child is alive. |
-| `signal-trap-exit(markerPath, delay)` | bash | Traps SIGTERM with a handler that sleeps for `<delay>` seconds then exits 0. On startup, writes `$$` to a marker file using `printf '%s'` and writes `"ready"` to stderr. Used for grace-period tests — delay < 5s tests clean exit, delay > 5s tests SIGKILL escalation. |
-| `signal-trap-ignore(markerPath)` | bash | Traps SIGTERM and ignores it (handler is a no-op). On startup, writes `$$` to a marker file using `printf '%s'` and writes `"ready"` to stderr, then sleeps indefinitely. Used for SIGKILL-after-grace-period tests (T-SIG-05). |
+| `signal-trap-exit(markerPath, delay, signal?)` | bash | Traps the named signal (`signal` defaults to `TERM`; supply `INT` for SIGINT-parameterized variants like T-SIG-04a) with a handler that sleeps for `<delay>` seconds then exits 0. On startup, writes `$$` to a marker file using `printf '%s'` and writes `"ready"` to stderr. Used for grace-period tests — delay < 5s tests clean exit, delay > 5s tests SIGKILL escalation. |
+| `signal-trap-ignore(markerPath, signal?)` | bash | Traps the named signal (`signal` defaults to `TERM`; supply `INT` for SIGINT-parameterized variants like T-SIG-05a) and ignores it (handler is a no-op). On startup, writes `$$` to a marker file using `printf '%s'` and writes `"ready"` to stderr, then sleeps indefinitely. Used for SIGKILL-after-grace-period tests (T-SIG-05 / T-SIG-05a). |
 | `spawn-grandchild(markerPath)` | bash | Spawns a background subprocess (e.g., `sleep 3600 &`), writes both `$$` (script PID) and `$!` (grandchild PID) to a marker file (one per line) using `printf '%s\n'`, writes `"ready"` to stderr, then `wait`s. For process group signal tests (T-SIG-06). |
 | `write-pid-to-file(markerPath)` | ts | Writes `process.pid` to a marker file using `fs.writeFileSync`, writes `"ready"` to stderr, then runs a long-running operation (e.g., `setTimeout(() => {}, 999999)`). Used for API cancellation tests (T-API-09a, T-API-10a) where a JS/TS script is needed. |
 | `counter(file)` | bash | Appends "1" to a counter file each invocation, outputs count as result |
 
 **Fixture naming note:** The `emit-*` fixtures replace the previous `echo-*` fixtures. `printf` is used instead of `echo` to provide exact byte control — `echo` appends a trailing newline which can mangle exact byte expectations in parser tests. For tests that specifically need to verify trailing-newline handling, use `emit-raw-ln`. The `write-*-to-file` fixtures observe values via the filesystem rather than CLI stdout, since the CLI never prints `result` to its own stdout (Spec 7.1). All bash `write-*-to-file` fixtures use `printf '%s'` (not `echo`) to write values, ensuring exact-byte safety for trailing spaces, backslashes, and values starting with `-`. The `observe-env` fixture is a TS-based alternative to `write-env-to-file` that writes structured JSON (`{ "present": boolean, "value"?: string }`) to a marker file using `fs.writeFileSync` for exact-byte safety. Use `observe-env` when a test must distinguish between a variable being unset vs set to an empty string — `write-env-to-file` (bash `printf '%s' "$VAR"`) produces identical output for both cases.
 
+**cwd-observation fixture selection.** Three fixtures observe working-directory-related state and must not be confused, because Spec 6.1 explicitly partitions them:
+
+- `write-cwd-to-file` (bash) — authoritative for Bash cwd assertions. Calls `/bin/pwd -P`, which reports the kernel cwd spelling via `getcwd(3)`. Do **not** use `$PWD` for cwd assertions: `$PWD` is shell-maintained, inherited unchanged from loopx, and Spec 6.1 disclaims any byte-for-byte equality between `$PWD` and the spawn cwd.
+- `observe-cwd-ts` (ts) — authoritative for JS/TS cwd assertions. Writes `process.cwd()` via `fs.writeFileSync`. Node/Bun's `process.cwd()` typically canonicalizes via `getcwd(3)`, so the runtime may report a different string spelling than loopx used to spawn — directory identity (device/inode) is guaranteed; string spelling is not.
+- `observe-pwd` (bash) — retained **only** for a narrow class of tests that specifically want to observe Bash's shell-managed `$PWD` variable. **Not used for exact-value `PWD` passthrough assertions** — per Spec 6.1 / 8.3 / 13, Bash may rewrite `$PWD` during shell startup under normal POSIX / Bash semantics, so byte-for-byte equality between Bash `$PWD` and a caller-supplied value is not a loopx guarantee. Tests that want to verify "loopx does not set `PWD`" or "`RunOptions.env`-supplied `PWD` reaches the child" (T-PWD-01 / 02 / 03 / 06) use `observe-env` with variable name `PWD` instead — that TS fixture reads `process.env.PWD` directly under Node / Bun, which preserves the inherited value byte-for-byte and bypasses Bash's shell-level rewrite.
+
+**Tmpdir/workflow-dir observation fixtures.** See `observe-env` (reused with `LOOPX_TMPDIR` and `LOOPX_WORKFLOW_DIR` as the variable name) for structured `{ "present": bool, "value"?: string }` marker files needed by the section 7.4 and `LOOPX_WORKFLOW_DIR` tests. A test that must both observe the env var **and** read/write files inside it (e.g., tmpdir persistence-across-iterations tests) uses `observe-env` plus a follow-up `write-value-to-file` / read pass inside the reported path.
+
 **Signal/cancellation fixtures:** The `signal-ready-then-sleep`, `signal-trap-exit`, `signal-trap-ignore`, `spawn-grandchild`, and `write-pid-to-file` fixtures are purpose-built for signal and cancellation tests. They all follow a common protocol: (1) write PID(s) to a marker file on startup, (2) write `"ready"` to stderr, (3) block. The stderr marker allows `waitForStderr("ready")` to synchronize the test harness before sending signals, preventing races. The marker file PIDs allow post-test verification that processes were actually killed.
 
 **Bash JSON safety warning:** The `emit-result`, `emit-goto`, and `emit-result-goto` fixtures use `printf` with `%s` substitution to produce JSON. This is only safe for simple string values that do not contain double quotes (`"`), backslashes (`\`), newlines, or other JSON-special characters — these would produce malformed JSON. For tests that require exact-byte control, JSON-special characters in values, or arbitrary binary content, use the `stdout-writer` TS fixture (which reads a pre-written payload from disk) or `emit-raw`/`emit-raw-ln` (which output exact bytes without JSON framing).
@@ -418,6 +857,8 @@ Each test is identified by a unique ID (`T-<SECTION>-<NUMBER>`), references a SP
 #### Help & Version
 
 - **T-CLI-01**: `loopx version` prints the bare package version string followed by a newline, exits 0. Assert exact stdout is `${version}\n` — the spec requires a trailing newline, so assert against the untrimmed stdout, not a trimmed comparison. No additional text or labels. Does not require `.loopx/` to exist. *(Spec 4.3, 5.4)*
+- **T-CLI-01a**: `loopx version extra` (extra positional after `version`) → usage error, exit 1. SPEC 4.3 specifies `loopx version` as a no-argument subcommand ("Prints the installed version of loopx to stdout and exits") and SPEC 12's usage-error enumeration uses non-exhaustive language ("Usage errors (exit code 1) include: …"), with the consistent pattern that extra positionals to fixed-grammar subcommands are usage errors (SPEC 12 explicitly lists `loopx run ralph bar` as the run-side analogue). Other no-argument subcommands have extra-argument coverage (e.g., T-CLI-RUN-DASHDASH-01 for `loopx run --`); the version-subcommand surface is uncovered. Run `loopx version extra`. Assert: (a) exit code 1, (b) stderr surfaces a usage / unrecognized-argument error (the exact wording is implementation-defined; the test does not pin a specific phrase but does require the failure category to be a parser-level usage error), (c) stdout does **not** contain the version string (the version-print short-circuit must not fire when the parser rejects the invocation). A buggy implementation that ignored extra positionals on `version` and printed the version anyway would surface as a stdout containing the version string (failing assertion (c)) and exit code 0 (failing (a)). The related `loopx version --help` / `-h` grammar is covered by T-CLI-01b under the same most-natural reading; both tests are outside the ADR-0004 surface and are maintained at the SPEC 4.3 / 11 / 12 grammar layer. *(Spec 4.3, 12)*
+- **T-CLI-01b**: `loopx version --help` and `loopx version -h` → usage error, exit 1. SPEC §11 (Help) defines exactly three help forms — top-level (11.1), run (11.2), and install (11.3) — with no "Version Help" section. SPEC 4.3's `loopx version` definition does not document a help form for the subcommand. The deliberate omission combined with the non-exhaustive usage-error enumeration in SPEC 12 makes the consistent reading "extra arguments to a no-argument subcommand are usage errors", which subsumes `--help` / `-h` as unrecognized arguments at the version-subcommand parser level. **Note:** SPEC is silent on this exact case; the test encodes the most-natural reading of SPEC 4.3 / 11 / 12 (usage error) and is outside the ADR-0004 surface — a follow-up SPEC clarification at the SPEC 4.3 / 11 layer would let this test be re-classified as a direct conformance pin instead of a grammar-derived reading. Run two variants: (a) `loopx version --help`, and (b) `loopx version -h`. For each variant, assert: (i) exit code 1, (ii) stderr surfaces a usage / unrecognized-argument error (the exact wording is implementation-defined), (iii) stdout does **not** contain the version string, and (iv) stdout does **not** contain a version-scoped help block (no "Usage: loopx version ..." or similar synopsis text — the version subcommand has no help form per SPEC §11). A buggy implementation that interpreted `--help` as a top-level help short-circuit when reached via the `version` subcommand path would print top-level help and exit 0, failing (i)–(iv). *(Spec 4.3, 11, 12)*
 
 #### Top-Level Help
 
@@ -434,11 +875,13 @@ Each test is identified by a unique ID (`T-<SECTION>-<NUMBER>`), references a SP
 - **T-CLI-61**: `loopx --help run foo` shows top-level help (not run help) and exits 0. Same behavior as `loopx -h run foo` — verifies that the `--help` long form has identical precedence semantics to `-h` when followed by additional arguments. *(Spec 4.2)*
 - **T-CLI-90**: `loopx --help --invalid-flag` prints top-level help and exits 0 (top-level `--help` takes precedence over invalid flags). This is the `--help` long-form counterpart to T-CLI-07g (`loopx -h --invalid-flag`), verifying both help spellings suppress subsequent invalid flags identically. *(Spec 4.2)*
 - **T-CLI-91**: `loopx --help -e nonexistent.env` prints top-level help and exits 0 (top-level `--help` takes precedence over `-e`). The nonexistent env file is not read or validated. This is the `--help` long-form counterpart to T-CLI-07j (`loopx -h -e nonexistent.env`). *(Spec 4.2)*
+- **T-CLI-TOP-DASHDASH-01**: Top-level `loopx --` rejected as an unrecognized top-level token. SPEC 4.2 / 4.3 / 12 do not list `--` as a recognized top-level flag or separator — the only top-level surfaces are help (`-h` / `--help`), the recognized subcommands (`run`, `version`, `output`, `env`, `install`), and parser-level validation. T-CLI-RUN-DASHDASH-01 covers `loopx run --` (which is a `run`-subcommand-scoped concern); this test pins down the **top-level** parser's rejection of `--` as a usage error. Run `loopx --` (no subcommand, no other arguments). Assert: (a) exit code 1 (usage error per SPEC 12), (b) stderr mentions an unrecognized argument / missing subcommand / unrecognized `--` token (the exact wording is implementation-defined; the test does not pin a specific message phrase but does require the error to surface a usage-error category), (c) no subcommand was dispatched (no version output, no help short-circuit, no install or run side effects). A buggy implementation that silently consumed `--` at the top-level (e.g., as a no-op separator) would proceed to a "no subcommand provided" path or a top-level-help path; both are observable distinct failure modes. *(Spec 4.2, 4.3, 12)*
 
 #### Run Help
 
 - **T-CLI-40**: `loopx run -h` with `.loopx/` containing workflows prints run-specific help that includes: (a) run syntax showing the target form (e.g., `loopx run [options] <workflow>[:<script>]` or equivalent), (b) the `-n` and `-e` options with descriptions, and (c) a list of discovered workflows and their scripts. If a workflow has an `index` script, it is indicated as the default entry point. Exits 0. *(Spec 4.2, 11.2)*
 - **T-CLI-40a**: `loopx run -h` advertises the workflow-based invocation grammar, not the legacy flat-script form. Assert that the run help usage line presents the workflow-based target form (e.g., `<workflow>[:<script>]` or equivalent) as the positional argument. The positive check for the correct grammar is more robust than blacklisting individual words. Additionally verify that the usage line does not show `<script>` as a bare top-level positional argument (the old flat-script form was `loopx run [options] <script>`). This is the run-help counterpart to T-CLI-02's grammar assertions, applied to the `run` subcommand where ADR-0003 changed the grammar most directly. *(Spec 4.2, 11.2)*
+- **T-CLI-40b**: `loopx run -h` help text reflects the SPEC 11.2 / 12 limits: no `--` end-of-options marker and no `name=value` named-argument tail **in the usage grammar**. Parser-level rejection is covered by T-CLI-RUN-DASHDASH-01–05 and T-CLI-RUN-NAMEVAL-01–03, but the **help-text reflection** of those limits is not currently asserted. Per SPEC 11.2 "The printed usage reflects these limits." Run `loopx run -h`; capture stdout. Assert structurally on the **usage / synopsis lines only** (the `Usage: loopx run ...` line(s) and any structured synopsis grammar; **not** explanatory prose elsewhere in the help): (a) the usage line does not contain a `[--]` / `[-- ...]` / trailing `--` placeholder / similar end-of-options token (the usage shows the workflow-based target form only, without an end-of-options separator), and (b) the usage line does not show a named-argument tail — specifically, no `[name=value...]`, no `[<var>=<value>...]`, no `[KEY=VALUE...]` placeholder appearing **after the target argument or after `--`** as part of the synopsis grammar. **Crucially, the test must not forbid every literal occurrence of `key=value` text in stdout** — SPEC 11.2 itself explicitly mentions the shell env prefix `key=value loopx run <target>` as the sole per-run parameterization surface (also referenced in SPEC 8.3 and 9.5), so explanatory prose, examples, or option descriptions that mention the shell env prefix in the form `key=value loopx run <target>` (where the `key=value` precedes `loopx run`, not follows the target) are conformant and must be allowed. To distinguish synopsis grammar from prose: scope the assertions to the contiguous `Usage:` / `Synopsis:` block(s) at the top of the help output (the leading section delimited by a blank line and/or an `Options:` / `Examples:` section header), and within that block, assert that no `=`-bearing positional token appears **after the target placeholder or after `--`**. A buggy help-text that advertises a removed grammar surface (e.g., `loopx run [options] <target> [name=value...]` in the usage) would fail this test, while a help-text that explains the shell env prefix in the Examples section ("Use `MYVAR=value loopx run ralph` to inject `MYVAR` into scripts") would correctly pass. This is the help-text consequence of SPEC 11.2's "reflects these limits" clause and the ADR-0004 §5 decision not to adopt `--` as an end-of-options marker or a `name=value` named-argument tail in `run`'s argument list. *(Spec 11.2, 12, 4.1, 4.2, 8.3)*
 - **T-CLI-41**: `loopx run --help` produces identical stdout, stderr, and exit code as `loopx run -h`. Run both in the same fixture containing `.loopx/` with valid workflows and a name collision (e.g., `check.sh` and `check.ts` in the same workflow). Assert: (a) stdout is byte-identical between the two invocations, (b) stderr is byte-identical (both should contain the same non-fatal discovery/validation warnings — collision warnings), and (c) both exit 0. This proves the `--help` long form is a true alias for `-h` including non-fatal warning behavior, not just a help-text match in a clean fixture. *(Spec 4.2, 11.2)*
 - **T-CLI-42**: `loopx run -h` without `.loopx/` directory still prints run help with a warning that the directory was not found. The discovered-workflows section is omitted. Exits 0. *(Spec 11.2)*
 - **T-CLI-43**: `loopx run -h` with `.loopx/` containing name collisions (e.g., `check.sh` and `check.ts` in the same workflow) prints run help with warnings on stderr about the conflicting entries. Exits 0. *(Spec 5.2, 11.2)*
@@ -477,11 +920,19 @@ Within `run`, `-h` / `--help` is a full short-circuit: when present, loopx shows
 - **T-CLI-67**: `loopx run ralph -h --unknown` shows run help and exits 0. The `-h` after the target name triggers the help short-circuit, suppressing the unknown flag error. *(Spec 4.2)*
 - **T-CLI-68**: `loopx run ralph -h -e missing.env` shows run help and exits 0. The `-h` after the target name triggers the help short-circuit, suppressing env file validation. *(Spec 4.2)*
 - **T-CLI-69**: `loopx run --help --unknown` shows run help and exits 0. Verifies that the `--help` long form inherits the full ignore-everything-else short-circuit semantics, not just help display. *(Spec 4.2)*
+- **T-CLI-69a**: `loopx run --help -- ralph` shows run help and exits 0. Verifies that the `--help` long form suppresses the `--` usage error identically to `-h` (long-form counterpart to T-CLI-RUN-DASHDASH-04). *(Spec 4.2)*
 - **T-CLI-70**: `loopx run ralph --help -e missing.env` shows run help and exits 0. Verifies that the `--help` long form after a target name suppresses env file validation identically to `-h`. *(Spec 4.2)*
+- **T-CLI-70a**: `loopx run --help ralph adr=0003` shows run help and exits 0. Verifies that the `--help` long form suppresses extra-positional / `name=value` errors identically to `-h` (long-form counterpart to T-CLI-RUN-DASHDASH-05). *(Spec 4.2)*
 - **T-CLI-92**: `loopx run -h -n` shows run help and exits 0 (missing `-n` operand not rejected under help). *(Spec 4.2)*
 - **T-CLI-93**: `loopx run -h -e` shows run help and exits 0 (missing `-e` operand not rejected under help). *(Spec 4.2)*
 - **T-CLI-94**: `loopx run --help -n` shows run help and exits 0 (long-form help, missing `-n` operand not rejected). *(Spec 4.2)*
 - **T-CLI-95**: `loopx run --help -e` shows run help and exits 0 (long-form help, missing `-e` operand not rejected). *(Spec 4.2)*
+- **T-CLI-123**: `loopx run -n -h` shows run help and exits 0. A naive parser would consume `-h` as the operand for `-n`, but the `-h` short-circuit fires unconditionally when `-h` is present — all other run-level arguments are ignored. This is the would-be-operand counterpart to T-CLI-92 (`-h -n` — `-n` appears after `-h` so no operand is consumed) and mirrors install-side T-INST-49f (`install -w -h`). *(Spec 4.2)*
+- **T-CLI-124**: `loopx run -e -h` shows run help and exits 0. A naive parser would consume `-h` as the operand for `-e`, but the `-h` short-circuit fires unconditionally. Would-be-operand counterpart to T-CLI-93 (`-h -e`). *(Spec 4.2)*
+- **T-CLI-125**: `loopx run -n --help` shows run help and exits 0. Long-form counterpart to T-CLI-123: `-n` would consume `--help` as its operand in naive parsing, but the help short-circuit ignores all other arguments unconditionally. *(Spec 4.2)*
+- **T-CLI-126**: `loopx run -e --help` shows run help and exits 0. Long-form counterpart to T-CLI-124: `-e` would consume `--help` as its operand in naive parsing, but the help short-circuit ignores all other arguments unconditionally. *(Spec 4.2)*
+- **T-CLI-123a**: `loopx run ralph -n -h` shows run help and exits 0. Target-position variant of T-CLI-123: `-n` appears after the target name, and its would-be operand is `-h`. The help short-circuit fires unconditionally, even when the missing-operand pattern appears after the target. Together with T-CLI-68 (`run ralph -h -e missing.env` — target then help-first) this closes the run-help-after-target coverage for the would-be-operand case. *(Spec 4.2)*
+- **T-CLI-124a**: `loopx run ralph -e -h` shows run help and exits 0. Target-position variant of T-CLI-124: `-e` appears after the target name, and its would-be operand is `-h`. Help short-circuit fires unconditionally. *(Spec 4.2)*
 
 #### Late-Help Short-Circuit (Invalid Args Before `-h`)
 
@@ -503,6 +954,8 @@ Within `run`, `-h` / `--help` is a full short-circuit: when present, loopx shows
 - **T-CLI-33**: `loopx ralph` is a usage error (unrecognized subcommand, no implicit fallback to `run`). Create `.loopx/ralph/index.sh` that writes a known value to a marker file. Assert exit code 1 AND assert the marker file does not exist (proving the script was not executed despite being present). *(Spec 4.1)*
 - **T-CLI-34**: `loopx --unknown` is a usage error (unrecognized top-level flag). Exit code 1. *(Spec 4.2)*
 - **T-CLI-71**: `loopx -x` is a usage error (unrecognized top-level short flag). Exit code 1. *(Spec 4.2)*
+- **T-CLI-71a**: `loopx --unknown -h` is a usage error (exit code 1). The first argument is an unrecognized top-level flag, so the top-level help short-circuit does not apply. *(Spec 4.2)*
+- **T-CLI-71b**: `loopx --unknown --help` is a usage error (exit code 1). The first argument is an unrecognized top-level flag, so the top-level help short-circuit does not apply. *(Spec 4.2)*
 - **T-CLI-36**: `loopx -n 5 ralph` is a usage error (top-level `-n` rejected — only `-h` is recognized at top level). Exit code 1. *(Spec 4.2)*
 - **T-CLI-37**: `loopx -e .env ralph` is a usage error (top-level `-e` rejected). Exit code 1. *(Spec 4.2)*
 - **T-CLI-07b**: `loopx -n 5 -h` is a usage error (exit code 1). The first argument is `-n`, which is not `-h` and not a recognized subcommand, so top-level parsing fails before `-h` is reached. *(Spec 4.2)*
@@ -563,6 +1016,7 @@ Within `run`, `-h` / `--help` is a full short-circuit: when present, loopx shows
 - **T-CLI-18**: `loopx run -n abc ralph` exits with code 1 (usage error). *(Spec 4.2)*
 - **T-CLI-19**: `loopx run -n 0 nonexistent` with `.loopx/` existing but no workflow named `nonexistent` — exits with code 1 (validation occurs before `-n 0` short-circuit). *(Spec 4.2, 7.1)*
 - **T-CLI-19a**: `loopx run -n 0 ralph` with `.loopx/` directory missing entirely → exits with code 1. *(Spec 4.2, 7.1, 7.2)*
+- **T-CLI-19b**: `loopx run ralph` in a project with no `.loopx/` directory emits an error that instructs the user to create `.loopx/`. SPEC 7.2 specifies "When executing via `loopx run <target>`, if `.loopx/` does not exist, loopx exits with an error instructing the user to create it." Existing tests (T-CLI-19a, T-CLI-42, T-CLI-RUN-NAMEVAL-02, T-CLI-RUN-ORDER-04) assert exit code 1 and that stderr identifies the missing `.loopx/`, but none asserts the *creation-guidance* part of SPEC 7.2's error contract. Set up a fixture with no `.loopx/` directory. Run `loopx run ralph`. Assert: (a) exit code 1, (b) stderr mentions `.loopx/` (or `.loopx`) as the missing entity, and (c) **stderr contains actionable creation guidance** — the error message indicates how the user should remediate, structurally distinct from a bare "directory not found" error. Concrete acceptance signals (any one suffices, the test does not pin exact prose): a literal mention of creating, initializing, or making `.loopx/`; a suggested command (e.g., `mkdir .loopx`, `loopx install <source>`); an instruction to add or set up workflows; a "create it to get started" / "create one to..." style hint; etc. The check targets the presence of remediation language rather than a specific phrase, mirroring the structural-rather-than-prose pattern used in T-DISC-10a. A buggy implementation that emitted only a bare "no such directory: .loopx/" with no remediation guidance would fail (c) while still passing (a) and (b). *(Spec 7.2)*
 - **T-CLI-20**: `loopx run -n 1 ralph` runs exactly 1 iteration even if the script produces no `stop`. *(Spec 4.2)*
 - **T-CLI-56**: `loopx run -n 0 ralph` with a valid workflow performs discovery and validation (target must exist), then executes zero iterations, and exits 0. *(Spec 4.2, 7.1)*
 - **T-CLI-119**: `loopx run -n 0 ralph` skips workflow-level version checking. Set up `.loopx/ralph/package.json` declaring a loopx version range not satisfied by the running version. Assert exit code 0 and no version mismatch warning on stderr. *(Spec 3.2, 4.2)*
@@ -592,6 +1046,32 @@ Within `run`, `-h` / `--help` is a full short-circuit: when present, loopx shows
 - **T-CLI-88**: `loopx run ralph -n 1 -n 2` exits with code 1 (duplicate `-n` after target name). *(Spec 4.2)*
 - **T-CLI-89**: `loopx run ralph -e a.env -e b.env` exits with code 1 (duplicate `-e` after target name). *(Spec 4.2)*
 
+#### End-of-Options `--` and `name=value` Target Parsing
+
+Per Spec 11.2 / 12, `loopx run` does not accept `--` as an end-of-options marker and does not accept a named-argument tail; the shell env prefix (`key=value loopx run <target>`) is the sole CLI surface for per-run parameterization. These tests pin down the parser-level rejections.
+
+- **T-CLI-RUN-DASHDASH-01**: `loopx run -- ralph` → usage error, exit code 1. Fixture contains a valid `.loopx/ralph/index.sh` so the test would succeed if `--` were silently stripped. Assert: (a) exit code 1, (b) stderr mentions the unrecognized `--` token (or similar "end-of-options not supported" wording), and (c) `.loopx/ralph/index.sh` did not run (no marker file). Per Spec 12 "usage errors". *(Spec 4.1, 4.2, 12)*
+- **T-CLI-RUN-DASHDASH-02**: `loopx run -n 1 -- ralph` → usage error, exit code 1. Even when valid options precede `--`, the marker is still rejected. Same assertions as T-CLI-RUN-DASHDASH-01. *(Spec 4.1, 4.2, 12)*
+- **T-CLI-RUN-DASHDASH-03**: `loopx run ralph -- name=value` → usage error, exit code 1. Proves `--` is not treated as a separator that would protect a trailing `name=value` from being parsed as an extra positional. Per Spec 12, `name=value` is not interpreted as a named argument and `--` is not a recognized separator — both conditions produce a usage error. *(Spec 4.1, 4.2, 12)*
+- **T-CLI-RUN-DASHDASH-04**: `loopx run -h -- ralph` → help short-circuit, exit 0. Despite the presence of `--` (which would otherwise be a usage error), the run-help `-h` short-circuit fires first. No parser rejection surfaces. Assert exit code 0 and run-help stdout. Mirrors the help-short-circuit pattern from T-CLI-07e / T-INST-42. *(Spec 4.2, 11.2)*
+- **T-CLI-RUN-DASHDASH-05**: `loopx run -h ralph adr=0003` → help short-circuit, exit 0. The `-h` short-circuit fires before the would-be "extra positional after target" error (T-CLI-96 without `-h`). Assert exit code 0 and run-help output. *(Spec 4.2, 11.2)*
+- **T-CLI-RUN-DASHDASH-06**: `loopx run --` (no target, just `--`) → usage error, exit code 1. Extends the `--` rejection coverage to the zero-arg-after-`--` form that T-CLI-RUN-DASHDASH-01/02/03 do not cover (they all have a `ralph` or `name=value` token after `--`). Assert: (a) exit code 1, (b) stderr mentions the unrecognized `--` token (per SPEC 12's enumerated usage errors), and (c) no `.loopx/ralph/index.sh` execution (no marker file). A parser that treated `--` as a no-op separator when followed by nothing — rather than consistently as "unrecognized token" — would fail this case while passing T-CLI-RUN-DASHDASH-01/02/03. *(Spec 4.1, 4.2, 12)*
+- **T-CLI-RUN-DASHDASH-07**: `loopx run ralph --` (target followed by trailing `--` with nothing after) → usage error, exit code 1. Counterpart to T-CLI-RUN-DASHDASH-06 with the target in play; extends T-CLI-RUN-DASHDASH-03 (which tests `loopx run ralph -- name=value`) by removing the post-`--` token to prove the trailing `--` is rejected on its own. Assert: (a) exit code 1, (b) stderr mentions the unrecognized `--` token, and (c) `.loopx/ralph/index.sh` did not run. *(Spec 4.1, 4.2, 12)*
+- **T-CLI-RUN-DASHDASH-08**: `loopx run -- -h` → run-help short-circuit, exit 0. Per SPEC 11.2 / ADR-0004 §5, the `run -h` / `--help` short-circuit ignores `--` "in any position" — including positions where `--` appears **before** the help flag. T-CLI-RUN-DASHDASH-04 covers `-h -- ralph` (help precedes `--`); this test covers the symmetric case where `--` precedes `-h`. A buggy parser that processed `--` left-to-right and rejected it as an unrecognized flag before scanning the rest of argv for `-h` / `--help` would surface a usage error instead of help; the help short-circuit must defeat that ordering. Assert: (a) exit code 0, (b) run-help is printed on stdout, (c) `.loopx/ralph/index.sh` is **not** executed (no marker file written; run help does not enter the execution pre-iteration sequence so no script is spawned — SPEC 11.2 non-fatal run-help discovery / validation warnings may still occur, but no `LOOPX_TMPDIR` is created and the target is not resolved for execution). *(Spec 4.2, 11.2)*
+- **T-CLI-RUN-DASHDASH-09**: `loopx run -- --help` → run-help short-circuit, exit 0. Long-form counterpart to T-CLI-RUN-DASHDASH-08 — same `--`-precedes-help structure, with `--help` rather than `-h`. Asserts the "any position" rule applies symmetrically across both help spellings. Same assertions as T-CLI-RUN-DASHDASH-08: exit 0, run-help on stdout, no script execution. *(Spec 4.2, 11.2)*
+- **T-CLI-RUN-DASHDASH-10**: `loopx run -e -- ralph` → usage error, exit code 1. Closes a real ADR-0004 parser gap that T-CLI-RUN-DASHDASH-01 / 02 / 03 / 06 / 07 do not exercise: a buggy parser could accept `--` in *positional* positions but still consume `--` as an *option operand* (the value after `-e`), leaving the rest of argv to be re-parsed and the run to proceed. SPEC 4.1 says `--` is rejected "wherever it appears" outside the `-h` / `--help` short-circuit — including the position where `--` could be misread as the `-e` operand. **Pre-create an actual file named `--`** in the project root (via `fs.writeFileSync(path.join(projectRoot, "--"), "MARKER=should-not-be-loaded\n1BAD=warning-if-loaded\n")`) so that an implementation that treats `--` as the `-e` operand would *successfully* find a readable env file and proceed to interpret `ralph` as the target — the existence of the file removes "missing env file" as an alternative failure surface and forces the assertion to discriminate between "parser correctly rejected `--`" and "parser consumed `--` as operand and the run proceeded." The `--` file deliberately includes both a valid sentinel line (`MARKER=should-not-be-loaded`) and a SPEC 8.1 invalid-key line (`1BAD=warning-if-loaded`) so that an implementation that **loaded** the env file before parser validation would emit the SPEC 8.1 invalid-key warning to stderr — the warning is an externally observable side-effect of env-file loading that does not depend on a child spawn (which (c) below pins out). Create a valid `.loopx/ralph/index.sh` (writes a marker file on execution). Run `loopx run -e -- ralph` via the CLI. Assert: (a) exit code 1, (b) stderr surfaces a usage error (the `--` rejection or an equivalent "end-of-options not supported" / unrecognized-flag wording — the assertion is on the usage-error category, not on exact token echo, matching T-CLI-RUN-DASHDASH-01's broad-wording pattern), (c) `.loopx/ralph/index.sh` did not run (no marker file from `ralph:index`), and (d) **stderr does not contain the SPEC 8.1 invalid-key parser warning for `1BAD`** — i.e., stderr does not mention `1BAD` and does not surface the env-file invalid-key warning text. (d) is independently observable from (c): if the parser had consumed `--` as the `-e` operand and triggered env-file loading before usage validation, the malformed line `1BAD=warning-if-loaded` would have produced the SPEC 8.1 stderr warning regardless of whether any child was spawned. A future implementation that loaded the env file before parser validation would fail (d) even if (c) held. The `--` file is cleaned up by the test's normal fixture-teardown logic. *(Spec 4.1, 4.2, 8.1, 12)*
+- **T-CLI-RUN-DASHDASH-11**: `loopx run ralph -e --` → usage error, exit code 1. Counterpart to T-CLI-RUN-DASHDASH-10 with the target preceding the `-e --` sequence. Same parser gap: a buggy implementation could accept `ralph` as the target, consume `--` as the `-e` operand, and proceed. SPEC 4.1's "wherever it appears" applies symmetrically regardless of whether `--` shows up before or after the target. Same fixture as T-CLI-RUN-DASHDASH-10: pre-create a file named `--` in the project root containing `MARKER=should-not-be-loaded\n1BAD=warning-if-loaded\n` (so the SPEC 8.1 invalid-key line is present to make env-file-loading observable independently of any child spawn), plus `.loopx/ralph/index.sh` (writes a marker file). Run `loopx run ralph -e --` via the CLI. Assert: (a) exit code 1, (b) stderr surfaces a usage error (broad wording, same pattern as T-CLI-RUN-DASHDASH-10), (c) `.loopx/ralph/index.sh` did not run, and (d) **stderr does not contain the SPEC 8.1 invalid-key parser warning for `1BAD`** (does not mention `1BAD` and does not surface the env-file invalid-key warning text) — independently observable from (c) per the rationale in T-CLI-RUN-DASHDASH-10. Together with T-CLI-RUN-DASHDASH-10, this closes the option-operand-position branch of SPEC 4.1's `--` rejection — neither order ("flag-then-`--`-then-target" nor "target-then-flag-then-`--`") allows `--` to slip through as an operand. *(Spec 4.1, 4.2, 8.1, 12)*
+- **T-CLI-RUN-DASHDASH-12**: `loopx run -n -- ralph` → usage error, exit code 1, with the rejection specifically targeting `--` as an unsupported / unrecognized end-of-options token (not as an "invalid `-n` operand"). Closes the **other** option-operand position covered by ADR-0004's "`--` is rejected wherever it appears" rule: T-CLI-RUN-DASHDASH-10 / T-CLI-RUN-DASHDASH-11 cover the `-e` operand slot; this test covers the `-n` operand slot with `--` immediately following `-n`. SPEC 4.1 says `--` is rejected "wherever it appears" outside the `-h` / `--help` short-circuit — including the position where `--` could be misread as the `-n` operand. The SPEC-conformant rejection treats `--` as the offending token (an unrecognized flag / unsupported end-of-options marker), it does not accept `--` as an operand and then reject it as a non-numeric value. A parser that consumed `--` as the `-n` operand and then surfaced an "invalid `-n` operand" / non-integer-value error would still exit 1 but is **not** SPEC-conformant: that path treats `--` as having been validly accepted as an operand (just one with a bad value), exactly the parser shape SPEC 4.1 forbids. **Setup.** Create a valid `.loopx/ralph/index.sh` (writes a marker file on execution and emits `stop: true`). Run `loopx run -n -- ralph` via the CLI. Assert: (a) exit code 1, (b) stderr surfaces a usage-error referring to `--` as the offending token — the test accepts flexible wording for the rejection category (e.g., "unrecognized flag `--`", "`--` not supported as end-of-options marker", "unexpected token `--`", or any synonymous phrasing that **identifies `--` itself as the unsupported / unrecognized token**), but **must not** accept stderr text that frames the failure as "invalid value for `-n`", "non-integer `-n` operand", "`-n` requires a non-negative integer", or any wording that treats `--` as having been consumed as `-n`'s operand and then rejected on operand-value grounds. The test asserts on this discriminating axis (the offending-token surface) and not on exact phrasing of the `--`-rejection wording, (c) `.loopx/ralph/index.sh` did not run (no marker file was written), and (d) stderr does not mention an integer / numeric / operand-value validation failure for `-n`. The (b) / (d) pair is the load-bearing assertion: a buggy parser that consumed `--` as the `-n` operand and then surfaced an integer-validation failure would pass (a) and (c) but fail (b) / (d), surfacing the parser shape SPEC 4.1 forbids. Unlike T-CLI-RUN-DASHDASH-10 / T-CLI-RUN-DASHDASH-11, this test does **not** need a pre-created file named `--` or a SPEC 8.1 invalid-key discriminator: `-n` accepts a numeric operand, not a path, so env-file loading is not a side-channel — the offending-token assertion on stderr provides the discriminative power. *(Spec 4.1, 4.2, 12)*
+- **T-CLI-RUN-DASHDASH-13**: `loopx run ralph -n --` → usage error, exit code 1, with the rejection specifically targeting `--` as the offending token (not as an "invalid `-n` operand"). Counterpart to T-CLI-RUN-DASHDASH-12 with the target preceding the `-n --` sequence — symmetric to the T-CLI-RUN-DASHDASH-10 / T-CLI-RUN-DASHDASH-11 pair on the `-e` axis. Same parser-shape contract: SPEC 4.1's "wherever it appears" applies symmetrically regardless of whether `--` shows up before or after the target, and the rejection must treat `--` as the unsupported / unrecognized token, not as a successfully-consumed `-n` operand with a bad value. **Setup.** Create a valid `.loopx/ralph/index.sh` (writes a marker file on execution and emits `stop: true`). Run `loopx run ralph -n --` via the CLI. Assert: (a) exit code 1, (b) stderr surfaces a usage error referring to `--` as the offending token (same flexible-but-discriminating wording requirement as T-CLI-RUN-DASHDASH-12 — accepts any "unrecognized flag `--`" / "`--` not supported" / "unexpected token `--`" phrasing that identifies `--` itself; does **not** accept "invalid `-n` operand" / "non-integer value" / "`-n` requires a non-negative integer" / any wording that treats `--` as having been consumed as `-n`'s operand), (c) `.loopx/ralph/index.sh` did not run, and (d) stderr does not mention an integer / numeric / operand-value validation failure for `-n`. Together with T-CLI-RUN-DASHDASH-12, this closes the `-n` operand-position branch of SPEC 4.1's `--` rejection across both orderings (flag-then-`--`-then-target and target-then-flag-then-`--`); together with T-CLI-RUN-DASHDASH-10 / T-CLI-RUN-DASHDASH-11 (the `-e` operand-position pair), the four tests close the full "`--` cannot slip through as an option operand" axis for the two `run` options that consume operands (`-n` and `-e`). *(Spec 4.1, 4.2, 12)*
+- **T-CLI-RUN-NAMEVAL-04**: `loopx run adr=0003 -h` → run-help short-circuit, exit 0. Per SPEC 11.2 / ADR-0004 §5, the `run -h` / `--help` short-circuit ignores `name=value` tokens "in any position" — including positions where the `name=value` token appears **before** the help flag. T-CLI-RUN-DASHDASH-05 covers `-h ralph adr=0003` (help precedes `name=value` after a target); this test covers the symmetric case where `name=value` (here as a sole positional that would otherwise be parsed as an invalid target by T-CLI-RUN-NAMEVAL-01) precedes `-h`. A buggy parser that validated the `name=value` positional as a target before scanning argv for help would surface the invalid-target error instead of help. Assert: (a) exit code 0, (b) run-help is printed on stdout, (c) stderr does **not** surface the invalid-target / name-restriction-violation error (the would-be T-CLI-RUN-NAMEVAL-01 outcome must not appear), and (d) no `.loopx/` script execution occurs. *(Spec 4.2, 11.2)*
+- **T-CLI-RUN-NAMEVAL-05**: `loopx run ralph adr=0003 --help` → run-help short-circuit, exit 0. Per SPEC 11.2 / ADR-0004 §5, the help short-circuit ignores `name=value` tokens and extra positionals in any position. Combines two would-be usage errors: (i) extra positional after target (T-CLI-RUN-NAMEVAL-03 surface), and (ii) `name=value` token in argv (T-CLI-RUN-NAMEVAL-01 / 03 surface). T-CLI-RUN-DASHDASH-05 covers the same combination with `-h`; this test exercises the long-form `--help` for parity, ensuring the short-circuit accepts both spellings symmetrically across the "name=value before help" position. Same assertions as T-CLI-RUN-NAMEVAL-04: exit 0, run-help on stdout, no usage / target error on stderr, no script execution. *(Spec 4.2, 11.2)*
+- **T-CLI-RUN-NAMEVAL-01**: `loopx run adr=0003` with a valid `.loopx/` (containing a `ralph` workflow but no workflow or script named `adr` or `adr=0003`) → **invalid target error**, exit code 1. Per Spec 12 "Invalid target strings ... `loopx run adr=0003` parsed as a target" — loopx does not interpret `adr=0003` as a named argument. It is a single positional, parsed as a target string, which fails validation because `=` violates the name-restriction pattern `[a-zA-Z0-9_][a-zA-Z0-9_-]*`. Assert stderr mentions the invalid target / name-restriction violation. *(Spec 4.1, 12)*
+- **T-CLI-RUN-NAMEVAL-02**: `loopx run adr=0003` with **no** `.loopx/` directory → the missing `.loopx/` discovery error surfaces before target validation. Assert: exit code 1, and stderr mentions the missing `.loopx/` directory (not the invalid-target error as the surfaced failure). Per SPEC 7.1, CLI discovery runs before target resolution/validation. *(Spec 4.1, 5.1, 7.1, 12)*
+- **T-CLI-RUN-NAMEVAL-03**: `loopx run ralph adr=0003` → usage error (extra positional), exit code 1. The grammar accepts exactly one positional (the target). T-CLI-27 covers two bare positional words; this test pins down that a positional of the form `name=value` is also rejected as an extra positional, not silently consumed as a named-argument tail. *(Spec 4.1, 4.2, 12)*
+- **T-CLI-RUN-NAMEVAL-06**: `loopx run adr=0003 ralph` → usage error (extra positional / no named-argument syntax), exit code 1, no script execution. Closes the **positional-order** symmetric variant of the ADR-0004 CLI grammar rule that T-CLI-RUN-NAMEVAL-01 / T-CLI-RUN-NAMEVAL-03 do not cover. T-CLI-RUN-NAMEVAL-01 covers `loopx run adr=0003` as a sole positional (parsed as an invalid target string); T-CLI-RUN-NAMEVAL-03 covers `loopx run ralph adr=0003` (target precedes `name=value`); this test covers the inverse position with **`name=value` preceding** a valid target — which a buggy parser could mishandle in distinct ways from the trailing position: it could (a) accept the leading `name=value` as a hypothetical "named-argument prefix" and consume the following bare word as the target (silently exporting `adr=0003` to the spawned script's env), (b) accept the leading `name=value` as the target itself (a sole-positional misreading that ignores `ralph`), or (c) accept both positionals (no extra-positional rejection). The SPEC 4.1 / SPEC 12 grammar accepts exactly one positional, and `name=value` is not consumed as a named-argument tail in any position — so the correct behavior is a usage error. **Setup.** Create a valid `.loopx/ralph/index.sh` that writes a marker file on execution (so a buggy "consumed `adr=0003` as env-prefix and ran `ralph`" implementation is byte-distinguishable from a correctly-rejecting one). Run `loopx run adr=0003 ralph` via the CLI. Assert: (a) exit code 1, (b) stderr surfaces a usage error (extra positional / unrecognized argument-form / name-restriction violation — the assertion is on the usage-error category, not exact phrasing, matching the broad-wording pattern used in T-CLI-RUN-DASHDASH-01), (c) `.loopx/ralph/index.sh` did **not** run (no marker file written) — proves no silent consumption of `adr=0003` as a hypothetical named-argument prefix combined with target resolution on `ralph`, and (d) stderr does **not** mention `ralph` as a successfully-resolved-target-that-then-failed (e.g., no version-check warning, no script-not-found error referencing scripts under `ralph`) — the parser short-circuited before target resolution. The (c) assertion is the load-bearing one for the "no named-argument prefix" axis: a buggy parser that consumed `adr=0003` as env-prefix and `ralph` as the target would produce a marker file and fail (c). The (d) assertion guards against a buggy parser that resolved `ralph` as a target before recognizing the extra-positional violation, which would be observable as `ralph`-specific resolution side effects on stderr. *(Spec 4.1, 4.2, 12)*
+- **T-CLI-RUN-NAMEVAL-07**: `loopx run -n 1 adr=0003 ralph` → usage error (extra positional with `name=value` in argv), exit code 1, no script execution. Closes the **option-flag-then-`name=value`-then-target** ordering for the SPEC 4.1 / SPEC 12 "no named-argument tail" rule. T-CLI-RUN-NAMEVAL-06 covers the bare-`name=value`-then-target ordering; this test pins down the same "name=value cannot slip through as a named-argument prefix" contract when an option flag (`-n 1`) precedes the `name=value` token. A buggy parser that recognized `name=value` only when it appears immediately after the target (and rejected it correctly there per T-CLI-RUN-NAMEVAL-03) but consumed it as some kind of named-argument prefix when preceded by an option flag would be caught by this test. **Setup.** Create a valid `.loopx/ralph/index.sh` that writes a marker file on execution. Run `loopx run -n 1 adr=0003 ralph` via the CLI. Assert: (a) exit code 1, (b) stderr surfaces a usage error referring to the extra positional / unrecognized argument-form (broad-wording pattern), (c) `.loopx/ralph/index.sh` did **not** run (no marker file written), and (d) stderr does **not** indicate `ralph` was successfully resolved as a target before the parse failure. Together with T-CLI-RUN-NAMEVAL-06, this closes the leading-`name=value` ordering branch of the ADR-0004 CLI grammar rule across both bare-positional-prefix and flag-then-positional-prefix shapes — symmetric to how T-CLI-RUN-DASHDASH-* close the `--`-rejection axis across all positional and operand orderings. *(Spec 4.1, 4.2, 12)*
+- **T-CLI-RUN-INHERIT-01**: Per-run CLI parameterization via the **shell env prefix** (`adr=0003 loopx run ralph`) reaches the spawned script unchanged through the inherited-environment tier. Per SPEC 11.2 / 12 (and ADR-0004's "no CLI surface for `RunOptions.env`" rationale), the **shell env prefix** is the sole CLI surface for per-run parameterization — `adr=0003 loopx run review-adr` continues to work at the inherited-env tier. T-CLI-RUN-DASHDASH-* and T-CLI-RUN-NAMEVAL-* pin down the negative parser-rejection axis (no `--` separator, no `name=value` tail); this test pins down the **positive** counterpart by asserting that the shell-env-prefix mechanism is observable end-to-end on the spawned-script env. The harness does not literally invoke a shell to apply the prefix — instead it sets the named variable in the CLI process's inherited environment (which is what `key=value loopx run …` produces in any POSIX shell), making the assertion shell-implementation-independent. Set up `.loopx/ralph/index.sh` that observes `adr` via `observe-env` and emits `stop:true`. Spawn `loopx run -n 1 ralph` with `adr=0003` injected into loopx's inherited environment (the test driver's child-spawn `env` option, equivalent to running `adr=0003 loopx run ralph` from any POSIX shell). Assert: (a) exit code 0, (b) the `observe-env` marker for `adr` records `{ "present": true, "value": "0003" }` — the inherited shell-prefix value reached the spawned script via the inherited-env tier (SPEC 8.3 tier 5 — inherited system environment), (c) no `name=value` token appears in the loopx argv (the test injects `adr=0003` via the env option, **not** as an argv token — proving the shell env prefix is the only mechanism exercised, with no argv-tail path involved). T-ENV-24 covers the four-tier precedence chain for an arbitrary non-protocol variable (asserting `local` wins over `global` over `system`); this test isolates the **inherited-env tier alone** with the canonical `adr=0003` example from ADR-0004, providing direct traceability to the ADR-0004 "CLI per-run parameterization uses existing shell idioms" rationale. A buggy implementation that consumed `adr=0003` from argv as a named-argument tail (a misreading explicitly forbidden by SPEC 12 / T-CLI-RUN-NAMEVAL-03) would not be exercised by this test (the harness does not pass an argv token); but a buggy implementation that scrubbed `adr` from the inherited env before spawning the script (e.g., as a misguided "non-`LOOPX_*` variable doesn't belong in the script env" filter) would surface here as an absent or empty marker, failing (b). *(Spec 4.1, 4.2, 8.3, 11.2, 13)*
+
 #### Missing Flag Operands
 
 - **T-CLI-97**: `loopx run -n` (no operand for `-n`, no target) exits with code 1 (usage error). *(Spec 4.2)*
@@ -610,9 +1090,24 @@ Within `run`, `-h` / `--help` is a full short-circuit: when present, loopx shows
 - **T-CLI-22e**: `loopx run -n 0 ralph` with `.loopx/` containing a sibling with an invalid workflow name (e.g., `.loopx/-bad-workflow/index.sh`) → exits with code 1 (global validation catches the invalid workflow name before the `-n 0` short-circuit). This is the `-n 0` counterpart to T-DISC-47b (invalid workflow name in sibling, normal run mode). *(Spec 4.2, 5.3, 7.1)*
 - **T-CLI-22f**: `loopx run -n 0 -e unreadable.env ralph` where `unreadable.env` exists but is unreadable (e.g., mode 000) → exits with code 1. Env file readability validation fires before the `-n 0` short-circuit. This completes the local `-e` file failure coverage under `-n 0`: T-CLI-22a covers missing, T-CLI-22c covers malformed, and this test covers unreadable. **Conditional on `process.getuid() !== 0`.** *(Spec 4.2, 7.1, 8.2)*
 
+#### CLI Pre-iteration Ordering (discovery before env before target resolution)
+
+SPEC 7.1 defines a concrete CLI pre-iteration order: (1) discovery/validation, (2) env loading, (3) target resolution. When failures from different steps are both present, the earlier step's failure surfaces first. These tests pin down that ordering across all three step boundaries. Programmatic-API pre-iteration ordering is mostly implementation-defined (SPEC 4.1 / 9.3), so this block is CLI-only.
+
+- **T-CLI-RUN-ORDER-01**: Env-file error beats missing-workflow error. Create a valid `.loopx/ralph/index.sh` (so discovery and validation pass). Run `loopx run -e missing.env nonexistent`. Assert: (a) exit code 1, (b) stderr mentions the missing env file (e.g., `missing.env`), and (c) stderr does **not** mention the missing workflow (`nonexistent`) as the fatal error — target resolution was never reached. Per SPEC 7.1 step 2 runs before step 3. *(Spec 7.1, 4.2)*
+- **T-CLI-RUN-ORDER-02**: Env-file error beats invalid target. Create a valid `.loopx/ralph/index.sh`. Run `loopx run -e missing.env ":script"` (invalid target format). Assert: (a) exit code 1, (b) stderr mentions the missing env file, and (c) stderr does **not** mention the invalid-target validation error as the fatal error. Invalid targets are rejected at the target-resolution point (SPEC 4.1: "at the same point as a missing workflow (after discovery)"), so an env-file failure must beat them too. *(Spec 7.1, 4.1, 4.2)*
+- **T-CLI-RUN-ORDER-03**: Discovery / global-validation error beats env-file error. Create a valid target workflow `.loopx/ralph/index.sh` and a **broken** sibling workflow `.loopx/broken/check.sh` + `.loopx/broken/check.ts` (same-base-name collision per SPEC 5.2 — fatal across all discovered workflows per SPEC 5.4). Run `loopx run -e missing.env ralph`. Assert: (a) exit code 1, (b) stderr mentions the sibling collision (e.g., references `broken` and the conflicting `check.sh` / `check.ts` entries), and (c) stderr does **not** mention the missing env file as the fatal-exit reason — discovery failed first (SPEC 7.1 step 1 before step 2), so env-file loading was never attempted. This closes the discovery-before-env ordering gap that T-CLI-RUN-ORDER-01 / T-CLI-RUN-ORDER-02 do not cover; together the three tests pin down the full SPEC 7.1 pre-iteration ordering `step 1 → step 2 → step 3`. *(Spec 7.1, 5.2, 5.4, 4.2)*
+- **T-CLI-RUN-ORDER-04**: Missing `.loopx/` beats env-file error. Set the fixture cwd to a directory with no `.loopx/` subdirectory. Run `loopx run -e missing.env ralph`. Assert: (a) exit code 1, (b) stderr mentions the missing `.loopx/` directory (per SPEC 7.2's "Missing `.loopx/` directory" clause and T-CLI-42 / T-DISC-10a coverage), and (c) stderr does **not** mention the missing env file as the fatal-exit reason — the missing-`.loopx/` check is part of discovery (step 1) and fails before env-file loading (step 2). This is the existence-branch counterpart to T-CLI-RUN-ORDER-03 (validation-branch of discovery): together they cover both sub-paths of SPEC 7.1's step 1 — missing-`.loopx/` and sibling-validation — each beating env-file loading. *(Spec 7.1, 5.1, 7.2, 4.2)*
+- **T-CLI-RUN-ORDER-05**: Env-file error beats workflow `package.json` / version-check warnings. SPEC 7.1 orders pre-iteration as discovery (step 1) → env loading (step 2) → target resolution (step 3) → workflow-entry version check (step 5). T-CLI-RUN-ORDER-01 / 02 prove env loading beats target resolution; T-CLI-RUN-ORDER-03 / 04 prove discovery beats env loading. This test pins down the *next* boundary: env-file failure (step 2) prevents the workflow `package.json` warning paths from running at all (step 5 never executes). Two parallel sub-cases that share the same fixture shape, run independently:
+    - **(05-bad-json)**: Create `.loopx/ralph/index.sh` (a runnable script that writes a marker file on entry) and `.loopx/ralph/package.json` containing `{{{INVALID` (broken JSON — would normally trigger the SPEC 3.2 "invalid JSON" warning on workflow entry). Run `loopx run -e missing.env ralph`. Assert: (a) exit code 1, (b) stderr mentions the missing env file `missing.env` as the fatal-exit reason, (c) stderr contains **no** `package.json` parse warning for `ralph` (the workflow-entry version check at SPEC 7.1 step 5 was never reached), and (d) the marker file does **not** exist (the script never ran).
+    - **(05-bad-range)**: Same fixture as (05-bad-json) but `.loopx/ralph/package.json` contains `{ "dependencies": { "loopx": ">=999.0.0" } }` (valid JSON with an unsatisfied loopx range — would normally trigger the SPEC 3.2 version-mismatch warning on workflow entry). Run `loopx run -e missing.env ralph`. Assert: (a) exit code 1, (b) stderr mentions the missing env file as the fatal-exit reason, (c) stderr contains **no** version-mismatch warning for `ralph` (the workflow-entry version check was never reached), and (d) the marker file does **not** exist.
+  
+  The two sub-cases together prove the SPEC 7.1 ordering rule across both `package.json`-failure branches that produce stderr output (invalid JSON, unsatisfied range). The unreadable-`package.json` and invalid-semver-range branches are not separately exercised because they share the same step-5 trigger point: the test's contract is that step 5 is never reached, and the bad-JSON / bad-range pair already excludes the bulk of the warning surface. CLI-only — programmatic-API non-abort pre-iteration ordering is intentionally implementation-defined per SPEC 4.1 / 9.3. *(Spec 7.1, 3.2, 8.2, 4.2)*
+
 #### CLI Stdout Silence
 
 - **T-CLI-23**: `loopx run -n 1 ralph` where `ralph:index` outputs `{"result":"hello"}` and writes a marker file — the CLI's own stdout is empty (result is not printed), AND the marker file exists (proving the script actually ran). *(Spec 7.1)*
+- **T-CLI-23a**: CLI stdout silence on **raw (non-JSON) successful** script output. SPEC 7.1 normatively says "The CLI does not print `result` to its own stdout at any point" and SPEC 2.3 says "If stdout is not valid JSON, is not an object, or is a valid JSON object but contains none of the known fields, the entire stdout content is treated as `{ result: <raw output> }`." T-CLI-23 covers structured JSON success (`{"result":"hello"}`); T-LOOP-24a covers the failure path (script writes structured-looking content, exits non-zero, the CLI must not pass it through). Neither covers the raw-stdout success path: a script that writes plain text to stdout and exits 0. A buggy implementation could route raw-stdout success through to the CLI's own stdout while correctly suppressing the structured-JSON case (e.g., "if I parsed it as structured output, suppress; otherwise pass through") — that bug would pass T-CLI-23 and T-LOOP-24a but break the SPEC 7.1 contract. Set up `.loopx/ralph/index.sh` that writes a raw non-JSON string to stdout (e.g., `printf '%s\n' 'hello raw'` or `echo "hello raw"`) and writes a marker file to confirm execution, then `exit 0`. Run via `runCLI(["run", "-n", "1", "ralph"])`. Assert: (a) exit code 0 (clean exit — the loop reset and `-n 1` capped iterations, not a script failure), (b) the CLI's captured **stdout is byte-empty** — the literal string `hello raw` does not appear on stdout, (c) the marker file exists (proving the script actually ran), and (d) the script's stderr (if any) passes through normally — but the test does not exercise stderr beyond confirming nothing leaked to stdout. Together with T-CLI-23 (structured success) and T-LOOP-24a (failure with structured-looking content), this closes the three success-or-failure × structured-or-raw quadrants of the CLI-stdout-silence contract. *(Spec 2.3, 7.1)*
 - **T-CLI-27**: `loopx run ralph beta` (two positional arguments within `run`) exits with code 1. `run` accepts exactly one positional argument. *(Spec 4.1)*
 - **T-CLI-96**: `loopx run ralph -n 1 beta` exits with code 1 (extra positional argument interleaved with options). *(Spec 4.1)*
 
@@ -638,9 +1133,14 @@ Within `run`, `-h` / `--help` is a full short-circuit: when present, loopx shows
 - **T-SUB-03**: `loopx output --stop` prints valid JSON to stdout, exits 0. Parse stdout as JSON and assert `stop === true`. *(Spec 4.3)*
 - **T-SUB-04**: `loopx output --result "x" --goto "y" --stop` prints valid JSON to stdout. Parse as JSON and assert all three fields present with correct values. *(Spec 4.3)*
 - **T-SUB-05**: `loopx output` with no flags exits with code 1 (error). *(Spec 4.3)*
+- **T-SUB-05a**: `loopx output --result ""` succeeds — an empty-string value still counts as a provided flag. SPEC 4.3 requires "at least one flag must be provided" and calling `loopx output` with no flags is an error (T-SUB-05). This test pins down that "provided" means the flag is on the command line, regardless of its value — `--result ""` is a provided flag with an empty-string value, not an absent flag. Run `loopx output --result ""`. Assert: (a) exit code 0, and (b) stdout is valid JSON with `result === ""` (the empty-string value is serialized as-is). An implementation that gated the "at least one flag" check on truthy/non-empty values would wrongly reject this call and match the T-SUB-05 path; this test catches that regression. *(Spec 4.3)*
 - **T-SUB-06**: `loopx output --result "x"` works without `.loopx/` directory existing. *(Spec 5.4)*
 - **T-SUB-06a**: `loopx output --result 'value with "quotes" and \\backslashes'` → stdout is valid JSON with the value correctly escaped. *(Spec 4.3)*
 - **T-SUB-06b**: `loopx output --result $'line1\nline2'` → stdout is valid JSON with the newline correctly escaped. *(Spec 4.3)*
+- **T-SUB-06c**: `loopx output --result` (missing operand for `--result`) → usage error, exit code 1. The SPEC 4.3 grammar `loopx output [--result <value>] [--goto <target>] [--stop]` requires an operand for `--result`; existing tests cover no-flags (T-SUB-05) and valid-flags but not the missing-operand sub-path. Run `loopx output --result`. Assert: (a) exit code 1, (b) stderr surfaces a usage-error category (missing-operand or "expected value after `--result`" — exact phrasing implementation-defined; the test does not pin a specific phrase), and (c) stdout does not contain JSON output. A buggy implementation that consumed nothing for `--result` and emitted a JSON object missing the `result` field would pass T-SUB-05 (which is no-flags) but fail this missing-operand check. *(Spec 4.3, 12)*
+- **T-SUB-06d**: `loopx output --goto` (missing operand for `--goto`) → usage error, exit code 1. Same shape as T-SUB-06c applied to the `--goto <target>` operand requirement. Same assertions: exit 1, stderr usage-error category, no JSON stdout. *(Spec 4.3, 12)*
+- **T-SUB-06e**: `loopx output --unknown` → usage error, exit code 1. SPEC 4.3 enumerates only `--result`, `--goto`, and `--stop`; an unrecognized flag is not a recognized output-helper token. Existing tests cover no-flags and valid-flags but not the unrecognized-flag sub-path. Run `loopx output --unknown`. Assert: (a) exit code 1, (b) stderr surfaces a usage-error category mentioning the unrecognized `--unknown` flag, and (c) no JSON stdout. A buggy implementation that silently ignored unrecognized flags and required only "at least one recognized flag" could pass T-SUB-05 (no-flags) and T-SUB-01 (valid `--result`) while accepting `loopx output --unknown --result foo` — the explicit unrecognized-flag check pins down rejection in the bare-unknown case. *(Spec 4.3, 12)*
+- **T-SUB-06f**: `loopx output --unknown --result x` → usage error, exit code 1. Strengthens T-SUB-06e by combining an unrecognized flag with a recognized one. T-SUB-06e covers the bare-unknown case (`--unknown` alone); a buggy implementation could pass T-SUB-06e by failing on "no recognized flag was provided" (the T-SUB-05 path) rather than on "unknown flag was rejected." This test pins down that the `--unknown` flag itself is rejected even when a recognized flag (`--result x`) is also present and would otherwise satisfy the "at least one flag must be provided" rule. Run `loopx output --unknown --result x`. Assert: (a) exit code 1, (b) stderr surfaces a usage-error category mentioning the unrecognized `--unknown` flag, and (c) **no JSON stdout** — the recognized `--result x` does not slip through despite the unknown flag's presence. A buggy implementation that silently ignored unrecognized flags would emit `{"result":"x"}` and exit 0, which this test catches. *(Spec 4.3, 12)*
 
 #### `loopx env set`
 
@@ -649,6 +1149,11 @@ Within `run`, `-h` / `--help` is a full short-circuit: when present, loopx shows
 - **T-SUB-09**: `loopx env set A1 val` succeeds (alphanumeric name). *(Spec 4.3)*
 - **T-SUB-10**: `loopx env set 1INVALID val` exits with code 1 (starts with digit). *(Spec 4.3)*
 - **T-SUB-11**: `loopx env set -DASH val` exits with code 1 (invalid name). *(Spec 4.3)*
+- **T-SUB-11b**: `loopx env set FOO-BAR val` exits with code 1. SPEC 4.3 specifies the env-set name pattern `[A-Za-z_][A-Za-z0-9_]*`. T-SUB-10 covers a digit-first invalid name and T-SUB-11 covers a dash-first invalid name (both reject at the first-character class), but neither exercises a name that starts with a valid first character and then contains a violating **interior** character. A buggy implementation that validated only the first character would accept this input and write an unparseable `FOO-BAR="val"\n` line into the global env file (which the loader would then reject per SPEC 8.1's env-file key-name rule). Run `loopx env set FOO-BAR val`. Assert: (a) exit code 1 (validation rejects the interior `-`), (b) stderr surfaces a name-validation error (exact phrasing implementation-defined), and (c) the global env file is not written / not modified — `loopx env list` after the failure does not include `FOO-BAR`. *(Spec 4.3, 8.1)*
+- **T-SUB-11c**: `loopx env set FOO.BAR val` exits with code 1. The interior `.` violates the pattern `[A-Za-z_][A-Za-z0-9_]*`. Same assertions as T-SUB-11b applied to the dot-interior case. Together with T-SUB-11b (dash interior), this pins down that interior-character validation rejects symbol classes that the first-character check passed unrelated. *(Spec 4.3, 8.1)*
+- **T-SUB-11d**: `loopx env set "FOO BAR" val` exits with code 1. The interior space violates the pattern. The argument is shell-quoted to ensure `argv` carries `FOO BAR` (the single 7-byte string `0x46 0x4f 0x4f 0x20 0x42 0x41 0x52`), not two separate `argv` tokens. Same assertions as T-SUB-11b / T-SUB-11c applied to the space-interior case. Together with T-SUB-11b (dash) and T-SUB-11c (dot), this closes the interior-character rejection coverage for the three most likely accidental inputs (hyphenated names from kebab-case, dotted names from dotted env-var schemes, and quoted-multi-word names typed by mistake). *(Spec 4.3, 8.1)*
+- **T-SUB-11e**: `loopx env set "" val` exits with code 1. The empty-string name has zero length and therefore cannot match the SPEC 4.3 pattern `[A-Za-z_][A-Za-z0-9_]*`, which requires at least one character. The argument is shell-quoted to ensure `argv` carries an empty-string token (not absent — that case is covered by T-SUB-25 / T-SUB-26 missing-operand grammar). Existing T-SUB-10 (digit-first), T-SUB-11 (dash-first), T-SUB-11b (dash interior), T-SUB-11c (dot interior), and T-SUB-11d (space interior) cover the non-empty invalid-name shapes; this test closes the zero-length branch. Run `loopx env set "" val` against an isolated global config (via `withGlobalEnv`). Assert: (a) exit code 1 (validation rejects the empty name), (b) stderr surfaces a name-validation error (exact phrasing implementation-defined), and (c) the global env file is not written / not modified — `loopx env list` after the failure does not include any zero-length-keyed entry, and any pre-existing variables remain untouched. A buggy implementation that accepted the empty name and committed `="val"` (or otherwise serialized a malformed line) would fail this test. *(Spec 4.3, 8.1)*
+- **T-SUB-11a**: `loopx env set lower_case_key val` succeeds. The SPEC 8.1 env-file key pattern `[A-Za-z_][A-Za-z0-9_]*` explicitly allows lowercase letters; `loopx env set` writes to the same env file and must accept the same key pattern. Existing `loopx env set` tests (T-SUB-08 underscore, T-SUB-09 alphanumeric `A1`) use names that begin with `_` or uppercase; none exercise a lowercase-first key. Run `loopx env set mykey myval`. Assert: (a) exit code 0, (b) `loopx env list` subsequently includes `mykey=myval`. An implementation that tightened the key-validation regex to `[A-Z_][A-Z0-9_]*` (an "uppercase convention" buglet) would fail this test. *(Spec 4.3, 8.1)*
 - **T-SUB-12**: `loopx env set FOO bar` then `loopx env set FOO baz` then `loopx env list` shows `FOO=baz` (overwrite). *(Spec 4.3)*
 - **T-SUB-13**: `loopx env set FOO bar` in a directory with no `.loopx/` → exits 0 AND `loopx env list` subsequently shows `FOO=bar`. *(Spec 5.4)*
 - **T-SUB-14**: `loopx env set` creates the config directory (`$XDG_CONFIG_HOME/loopx/`) if it doesn't exist. *(Spec 8.1)*
@@ -666,6 +1171,7 @@ Within `run`, `-h` / `--help` is a full short-circuit: when present, loopx shows
 - **T-SUB-14i**: `loopx env set FOO "value with spaces"` → file contains `FOO="value with spaces"\n`. *(Spec 4.3)*
 - **T-SUB-14j**: `loopx env set FOO 'val"ue'` → file contains `FOO="val"ue"\n` (no escaping). *(Spec 4.3)*
 - **T-SUB-14k**: `loopx env set FOO ""` (empty value) → file contains `FOO=""\n`. *(Spec 4.3)*
+- **T-SUB-14l**: `loopx env set` backslash round-trip — literal backslashes are stored and read back unchanged. Per SPEC 4.3 "the value is written literally within double quotes" (no escape sequences) and SPEC 8.1 "No escape sequence interpretation". The value under test is the exact 18-byte sequence `0x76 0x61 0x6c 0x5c 0x77 0x69 0x74 0x68 0x5c 0x62 0x61 0x63 0x6b 0x73 0x6c 0x61 0x73 0x68` (i.e., the string `val\with\backslash` containing exactly two literal `0x5c` backslash bytes, one between `val` and `with` and one between `with` and `backslash`). Pass this byte sequence to the CLI by any means that reaches `argv[n]` unchanged (e.g., shell-literal single-quoted argument, or `execa(..., ["env", "set", "KEY", "val\\with\\backslash"])` — where the JS source-level `\\` escape produces a single `0x5c` byte per pair, for a total of two backslash bytes). Run `loopx env set KEY <value>`. Assert: (a) the global env file on disk contains the exact byte sequence `KEY="val\with\backslash"\n` — specifically, `0x4b 0x45 0x59 0x3d 0x22 0x76 0x61 0x6c 0x5c 0x77 0x69 0x74 0x68 0x5c 0x62 0x61 0x63 0x6b 0x73 0x6c 0x61 0x73 0x68 0x22 0x0a` (key, `=`, opening quote, value bytes with the two literal `0x5c` bytes preserved, closing quote, newline; no escape-doubling applied at write time), and (b) a subsequent `loopx run` of a workflow that observes `$KEY` (via `write-env-to-file`) records the identical 18-byte value sequence in the marker file (no escape interpretation at read time). This is the combined write-side (SPEC 4.3) and read-side (SPEC 8.1) "no escape interpretation" assertion for the single value type most likely to reveal an accidental escape layer — a backslash-containing string. T-SUB-06a covers the *output* side's JSON-escaping of backslashes (CLI stdout); this test covers env-file serialization and round-trip through script spawn. *(Spec 4.3, 8.1)*
 
 #### `loopx env remove`
 
@@ -677,6 +1183,33 @@ Within `run`, `-h` / `--help` is a full short-circuit: when present, loopx shows
 - **T-SUB-17**: With no variables set, `loopx env list` produces no stdout output, exits 0. *(Spec 4.3)*
 - **T-SUB-18**: With variables `ZEBRA=z`, `ALPHA=a`, `MIDDLE=m` set, `loopx env list` outputs them sorted: `ALPHA=a`, `MIDDLE=m`, `ZEBRA=z`. *(Spec 4.3)*
 - **T-SUB-19**: `loopx env list` in a directory with no `.loopx/` → exits 0 and produces no stdout. *(Spec 5.4)*
+- **T-SUB-19a**: `loopx env list` parses a malformed global env file and reports only well-formed entries with a parser warning. SPEC 8.1 says env-file parsing applies to the global env file (loaded for runs and for `env list`); existing env-parser tests (T-ENV-15c and similar) drive parser behavior through `loopx run`, but do not cover the `env list` code path specifically. A buggy implementation could parse the file correctly for `run` but use a different code path for `env list` — e.g., reading raw lines without the parser — that skips the warning or includes malformed keys. Set up a global env file (via `withGlobalEnv`) containing raw lines `1BAD=val\nGOOD=ok\n` (first line has an invalid key per SPEC 8.1 `[A-Za-z_][A-Za-z0-9_]*`, second line is well-formed). Run `loopx env list`. Assert: (a) exit code 0 — malformed lines do not fail `env list`, only produce warnings, (b) stdout lists `GOOD=ok` exactly once (sorted output per T-SUB-18), (c) stdout does **not** contain `1BAD` (the malformed line was dropped), (d) stderr contains exactly one parser warning for the `1BAD=val` line (same warning class as T-ENV-15c when the same file is read under `loopx run`). This closes the gap in env-file parsing coverage between `run` and `env list` — a buggy implementation that maintained two separate parse paths would fail this test. *(Spec 4.3, 8.1, 5.4)*
+
+#### `loopx env` Grammar Coverage
+
+SPEC 4.3 defines exactly three `env` subcommands — `loopx env set <name> <value>`, `loopx env remove <name>`, and `loopx env list` — and no other forms. The tests in this block cover the grammar's missing-subcommand, missing-operand, and unrecognized-subcommand paths. Existing tests (T-SUB-07–19a) cover the success and validation paths for each subcommand individually, but do not pin down rejection of the malformed-grammar inputs that would result from typos or partial commands. The rejections follow from SPEC 4.3's grammar (no other forms accepted) and SPEC 12's usage-error contract for parser-level surface errors.
+
+- **T-SUB-24**: `loopx env` (no subcommand) → usage error, exit code 1. The bare `env` subcommand without any further token is not one of the three enumerated forms. Run `loopx env`. Assert: (a) exit code 1, (b) stderr surfaces a usage-error category (e.g., listing the valid subcommands `set` / `remove` / `list`, or a missing-subcommand error — exact phrasing implementation-defined), and (c) no env-file mutation occurred. A buggy implementation that defaulted to `list` (or any other subcommand) when none was specified would pass T-SUB-17 but fail this test. *(Spec 4.3)*
+- **T-SUB-25**: `loopx env set` (no name, no value) → usage error, exit code 1. The grammar requires `<name> <value>` after `set`. Assert: (a) exit code 1, (b) stderr surfaces a usage-error category mentioning the missing operands, and (c) no env-file mutation occurred (no key was written). *(Spec 4.3)*
+- **T-SUB-26**: `loopx env set FOO` (name only, missing value) → usage error, exit code 1. The grammar requires both `<name>` and `<value>` after `set`. Assert: (a) exit code 1, (b) stderr surfaces a usage-error category mentioning the missing value operand, and (c) no env-file mutation occurred — `loopx env list` after the failure does not include `FOO` (with any value, including empty-string — a buggy implementation that defaulted the missing value to `""` and committed `FOO=""` would fail this assertion). *(Spec 4.3)*
+- **T-SUB-27**: `loopx env remove` (no name) → usage error, exit code 1. The grammar requires `<name>` after `remove`. Assert: (a) exit code 1, (b) stderr surfaces a usage-error category mentioning the missing name operand, and (c) no env-file mutation occurred. A buggy implementation that defaulted the missing name to `""` and silently no-op'd (matching T-SUB-16's nonexistent-name silence) would pass T-SUB-16 but should fail this test — the nonexistent-name silence applies only when a name is supplied. *(Spec 4.3)*
+- **T-SUB-28**: `loopx env unknown` (unrecognized subcommand) → usage error, exit code 1. SPEC 4.3 enumerates only `set`, `remove`, and `list` under `env`; any other subcommand token is unrecognized. Run `loopx env unknown`. Assert: (a) exit code 1, (b) stderr surfaces a usage-error category mentioning the unrecognized subcommand `unknown` (or listing the valid subcommands — exact phrasing implementation-defined), and (c) no env-file mutation occurred. *(Spec 4.3)*
+- **T-SUB-29**: `loopx env list extra` (extra operand to `list`) → usage error, exit code 1. The `list` subcommand takes no operands per SPEC 4.3's grammar. Run `loopx env list extra`. Assert: (a) exit code 1, (b) stderr surfaces a usage-error category mentioning the extra positional, and (c) no stdout listing of variables (the failure short-circuits before `list`'s normal output path). A buggy implementation that ignored extra operands and ran `list` regardless would emit a sorted list and exit 0, which this test catches. The rejection follows directly from SPEC 4.3's `list` grammar (no operands) and SPEC 12's usage-error contract for parser-level surface errors. *(Spec 4.3, 12)*
+- **T-SUB-29a**: `loopx env set FOO bar extra` (extra operand after `set <name> <value>`) → usage error, exit code 1. The `set` subcommand grammar is `set <name> <value>` per SPEC 4.3; a third positional is outside the grammar. Run `loopx env set FOO bar extra` against an isolated global config (via `withGlobalEnv`). Assert: (a) exit code 1, (b) stderr surfaces a usage-error category mentioning the extra positional (exact phrasing implementation-defined), and (c) **no env-file mutation occurred** — the isolated global env file does not contain `FOO=bar` (or `FOO` at all) after the failure. A buggy implementation that accepted the extra operand and committed `FOO=bar` regardless would write the variable and fail this test. *(Spec 4.3, 12)*
+- **T-SUB-29b**: `loopx env remove FOO extra` (extra operand after `remove <name>`) → usage error, exit code 1. The `remove` subcommand grammar is `remove <name>` per SPEC 4.3. Pre-seed the isolated global config with `FOO=bar` (via `withGlobalEnv`). Run `loopx env remove FOO extra`. Assert: (a) exit code 1, (b) stderr surfaces a usage-error category mentioning the extra positional, and (c) **no env-file mutation occurred** — `FOO=bar` is still present after the failure (a buggy implementation that ignored the extra operand and removed `FOO` anyway would wipe the entry). *(Spec 4.3, 12)*
+- **T-SUB-29c**: `loopx output --result x extra` (extra positional after `--result` value) → usage error, exit code 1. The `output` subcommand accepts only the named flag-value pairs (`--result`, `--goto`, `--stop`) per SPEC 4.3 — no positional arguments are specified. Run `loopx output --result x extra`. Assert: (a) exit code 1, (b) stderr surfaces a usage-error category mentioning the extra positional `extra`, and (c) stdout is empty (no structured JSON was serialized — the usage error fired before the output-serialization path). A buggy implementation that ignored the extra operand and emitted `{"result":"x"}` would fail this test. *(Spec 4.3, 12)*
+- **T-SUB-29d**: `loopx output --stop extra` (extra positional after `--stop`) → usage error, exit code 1. The `output` subcommand's `--stop` is a boolean flag with no operand (unlike `--result` / `--goto`); a following positional is outside the grammar. Run `loopx output --stop extra`. Assert: (a) exit code 1, (b) stderr surfaces a usage-error category mentioning the extra positional, and (c) stdout is empty (no structured JSON serialized). Together T-SUB-29 / 29a / 29b / 29c / 29d pin down extra-positional rejection across `env set / remove / list` and `output --result / --stop`, following from SPEC 4.3's grammar + SPEC 12's usage-error contract. *(Spec 4.3, 12)*
+
+#### Broken `.loopx/` Tree is Ignored by Non-Validating Commands
+
+SPEC 5.4 specifies that `loopx env *` and `loopx output` do **not** validate `.loopx/`. Existing tests cover the "no `.loopx/` exists" case (T-SUB-06, T-SUB-13, T-SUB-19) but not the "broken `.loopx/` exists" case — a buggy implementation could ignore a missing `.loopx/` but still validate a broken one.
+
+All tests in this block share a fixture where `.loopx/` exists and contains a broken tree: an invalid workflow name (`.loopx/-bad-workflow/index.sh`), a same-base-name collision in another workflow (`.loopx/broken/check.sh` and `.loopx/broken/check.ts`), and an invalid script name (`.loopx/other/-bad.sh`). This is the same fixture shape used by T-INST-42c.
+
+- **T-SUB-20**: `loopx output --result "x"` with broken `.loopx/` tree → exits 0, prints valid JSON (same as T-SUB-01 in a clean fixture), and stderr contains no discovery or validation warnings. Per SPEC 5.4, `loopx output` does not validate `.loopx/`. A buggy implementation that validates when `.loopx/` is present would emit warnings here; this test catches that. *(Spec 4.3, 5.4)*
+- **T-SUB-21**: `loopx env list` with broken `.loopx/` tree and no env variables set → exits 0, produces no stdout, and stderr contains no discovery or validation warnings. Same assertion shape as T-SUB-20 applied to `env list`. *(Spec 4.3, 5.4)*
+- **T-SUB-22**: `loopx env set FOO bar` with broken `.loopx/` tree → exits 0, and stderr contains no discovery or validation warnings. Then `loopx env list` shows `FOO=bar`. Per SPEC 5.4, `env set` does not validate `.loopx/`. *(Spec 4.3, 5.4)*
+- **T-SUB-23**: `loopx env remove FOO` with broken `.loopx/` tree — after `loopx env set FOO bar` — exits 0, and stderr contains no discovery or validation warnings. Then `loopx env list` does not include `FOO`. *(Spec 4.3, 5.4)*
 
 ### 4.3 Workflow & Script Discovery
 
@@ -691,8 +1224,15 @@ Within `run`, `-h` / `--help` is a full short-circuit: when present, loopx shows
 - **T-DISC-05**: `.loopx/ralph/` containing `index.tsx` is a valid workflow. Assert via marker file. *(Spec 2.1, 5.1)*
 - **T-DISC-06**: `.loopx/ralph/` containing only `index.mjs` → not recognized as a workflow (`.mjs` is unsupported). `loopx run -n 1 ralph` fails with "not found." *(Spec 2.1, 5.1)*
 - **T-DISC-07**: `.loopx/ralph/` containing only `index.cjs` → not recognized as a workflow. *(Spec 2.1, 5.1)*
+- **T-DISC-07a**: `.mjs` and `.cjs` files are ignored during discovery when they coexist with valid scripts. Create `.loopx/ralph/index.sh` (valid workflow entry) and `.loopx/ralph/helper.mjs` (unsupported extension, coexisting with the valid script). Run `loopx run -n 1 ralph`. Assert: (a) exit code 0 — the `ralph:index` script runs (marker file written), (b) stderr contains no warning about `helper.mjs` being an unsupported extension (the `.mjs`/`.cjs` exclusion is silent, not a warning), (c) `loopx run -n 1 ralph:helper` fails with exit 1 and a "script not found" error — the `.mjs` file was not discovered as a `helper` script. T-DISC-06 / T-DISC-07 cover the "only-file unsupported" case where the workflow would not exist without the `.mjs`/`.cjs`; this test covers the coexistence case and is necessary because an implementation could plausibly discover `.mjs`/`.cjs` as scripts when a valid sibling script makes the directory a workflow. *(Spec 2.1, 5.1)*
+- **T-DISC-07b**: Same coexistence fixture as T-DISC-07a with `.cjs` instead of `.mjs`. `.loopx/ralph/index.sh` + `.loopx/ralph/helper.cjs`. Assert identical outcomes: `ralph:index` runs, no warning about `helper.cjs`, `ralph:helper` is not a discovered script. *(Spec 2.1, 5.1)*
+- **T-DISC-07c**: `loopx run -h` does not warn about `.mjs` / `.cjs` siblings of valid scripts. Same fixtures as T-DISC-07a and T-DISC-07b. Run `loopx run -h`. Assert: (a) exit 0, (b) the discovered-workflows section lists `ralph` with `index` as its default entry point — `helper` does not appear in `ralph`'s script list, (c) stderr contains no warning that mentions `helper.mjs` or `helper.cjs`. This is the help-mode counterpart to T-DISC-07a/07b and mirrors T-DISC-10d / T-DISC-10e (invalid-name loose files ignored under `-h`). *(Spec 2.1, 5.1, 11.2)*
+- **T-INST-42m**: Install-time — source workflow with valid `index.sh` plus top-level `.mjs`/`.cjs` non-script files. Unsupported extensions are copied as non-script workflow content, not treated as scripts or validated. Create a single-workflow source containing `index.sh` (valid script) and a top-level `helper.mjs` alongside a top-level `tool.cjs`. Run `loopx install <source>`. Assert: (a) exit code 0, (b) the workflow is installed at `.loopx/<name>/` and contains `index.sh`, `helper.mjs`, and `tool.cjs` byte-for-byte (`.mjs`/`.cjs` are workflow content, not script-discovery candidates), (c) stderr contains no validation warning about `helper.mjs` or `tool.cjs` being unsupported extensions (install-time validation per Spec 10.4 only checks **discovered** scripts; unsupported extensions are not discovered and therefore not validated against the name pattern), and (d) a subsequent `loopx run -n 1 <name>` runs `<name>:index` successfully, and `loopx run -n 1 <name>:helper` and `loopx run -n 1 <name>:tool` both fail with "script not found" (the install-time treatment of unsupported extensions matches the runtime-discovery treatment from T-DISC-07a/07b). This pins down that install-time workflow self-containment preserves non-script content alongside scripts without validating or flagging supported-extension-adjacent extensions. *(Spec 10.3, 10.4, 2.1, 5.1)*
+- **T-INST-42n**: Install-time — same-base-name collision immunity for unsupported `.mjs` / `.cjs` extensions. Install-time counterpart to T-DISC-24a / T-DISC-24b. SPEC 10.4's install-time validation reuses SPEC 5.2's collision rule, which applies only to discovered scripts; unsupported extensions are not discovery candidates and therefore cannot participate in same-base collision detection. A buggy installer that extension-fold-matched on base names (e.g., flagging `check.ts` + `check.mjs` as a `check` collision) would wrongly refuse install for sources whose contributors happened to ship companion `.mjs` / `.cjs` artifacts. Create a single-workflow source containing `check.ts` (valid script) and a top-level `check.mjs` and `check.cjs` (same base name, unsupported extensions — conceptually the kind of files a build pipeline might emit alongside the canonical `.ts` source). Run `loopx install <source>`. Assert: (a) exit code 0, (b) the workflow is installed at `.loopx/<name>/` and contains all three files (`check.ts`, `check.mjs`, `check.cjs`) byte-for-byte (the unsupported-extension siblings are copied as non-script content per T-INST-42m), (c) stderr contains no collision warning or error referencing `check.mjs` or `check.cjs` (install-time validation only flags collisions among **discovered** scripts), and (d) a subsequent `loopx run -n 1 <name>:check` runs `check.ts` successfully (marker file written) — proving that runtime discovery also resolves `check` to `check.ts` without same-base ambiguity, mirroring T-DISC-24a / T-DISC-24b. Together with T-INST-42m (mixed unsupported-extension content alongside a different-base-name script) and T-DISC-24a / T-DISC-24b (runtime same-base immunity), this closes the install + runtime same-base-collision-immunity coverage for `.mjs` / `.cjs`. *(Spec 10.3, 10.4, 2.1, 5.1, 5.2)*
 - **T-DISC-08**: `.loopx/ralph/` containing only `readme.txt` and `config.json` → not a workflow (no supported script extensions). `loopx run -n 1 ralph` fails. No warning. *(Spec 2.1, 5.1)*
 - **T-DISC-09**: Empty subdirectory `.loopx/ralph/` → not a workflow (no script files). `loopx run -n 1 ralph` fails. No warning. *(Spec 5.1)*
+- **T-DISC-09a**: A top-level entry inside a workflow whose **name** has a supported script extension but whose entry **type** is a directory does not count as a script — workflow detection requires top-level **files** with supported extensions. SPEC 5.1 / 2.1 say "A subdirectory is a workflow if it contains at least one **top-level** file (directly inside the subdirectory, not in nested subdirectories) with a supported extension"; the entry must be a **file**, not a directory whose name happens to end in `.sh`/`.ts`/`.js`/`.jsx`/`.tsx`. Set up `.loopx/ralph/index.sh/` (a directory, not a file — created with `mkdir -p .loopx/ralph/index.sh`) alongside a valid sibling workflow `.loopx/other/index.sh` (so `.loopx/` discovers at least one workflow). The directory `.loopx/ralph/index.sh/` has no top-level files of any kind inside it (or is empty). Run `loopx run -n 1 ralph`. Assert: (a) exit code 1, (b) stderr surfaces a missing-workflow / workflow-not-found error referring to `ralph` — `ralph` is not a discovered workflow because the only top-level entry inside it is a directory (which fails the "at least one top-level file with a supported extension" rule), not a missing-default-entry-point error (`ralph` does not exist as a workflow at all), (c) `.loopx/ralph/index.sh/` is silently ignored — no validation warning or error about its presence, (d) the sibling `.loopx/other/index.sh` is still discoverable, and `loopx run -n 1 other` succeeds. A buggy implementation that enumerated `.loopx/<dir>/` entries by name pattern (matching `*.sh` etc.) without checking whether the entry resolves to a regular file would wrongly classify `ralph/` as a workflow and surface a different error (e.g., "cannot execute `index.sh`: is a directory" at spawn time, or a discovery-level error confusingly reporting `index.sh` as a script). *(Spec 5.1, 2.1)*
+- **T-DISC-09b**: A top-level directory inside a workflow whose name shapes as `script.<supported-ext>` (e.g., `check.ts`) is not discovered as a script alongside a real `index.sh` file. SPEC 5.1 says scripts are top-level **files** with supported extensions; a directory whose name happens to end in a supported extension is not a script. Set up `.loopx/ralph/index.sh` (a real file, valid script) plus `.loopx/ralph/check.ts/` (a top-level directory whose name shape matches `*.ts` but is not a file — created with `mkdir -p .loopx/ralph/check.ts`). The directory may be empty or contain unrelated content (e.g., `.loopx/ralph/check.ts/notes.md`). Run `loopx run -n 1 ralph` (bare workflow, default entry). Assert: (a) exit code 0 — `ralph:index` runs (marker file written), (b) `loopx run -n 1 ralph:check` fails with exit code 1 and a "script not found" error — `check.ts` was a directory, not a file, so no `check` script was discovered. Additionally run `loopx run -h` and assert: (c) `ralph` is listed with `index` as a discovered script, (d) `check` does **not** appear in `ralph`'s script list, and (e) stderr contains no warning about `check.ts` being a directory — directory-shaped entries are silently ignored during script discovery, the same way nested subdirectories are ignored (T-DISC-14). A buggy implementation that lists names without checking entry types would wrongly add `check` to `ralph`'s script list and either fail to spawn it (a directory cannot be executed) or surface a confusing "script not found at spawn time" error. *(Spec 5.1, 2.1, 11.2)*
 - **T-DISC-10**: Files placed directly in `.loopx/` are never discovered. `.loopx/loose-script.sh` exists alongside `.loopx/ralph/index.sh`. `loopx run -n 1 loose-script` fails (not found). `loopx run -n 1 ralph` succeeds. *(Spec 5.1)*
 - **T-DISC-11**: `.loopx/loose-script.ts` directly in `.loopx/` is not discovered even if it has a supported extension. Assert `loopx run -n 1 loose-script` fails. *(Spec 5.1)*
 - **T-DISC-10a**: Flat-script explicit no-migration-warning test. `.loopx/loose-script.sh` exists alongside a valid workflow (`.loopx/ralph/index.sh`). `loopx run loose-script` fails with exit code 1 (not found). Additionally assert — **structurally** rather than by prose blacklisting — that stderr does not contain a migration-guidance or deprecation warning as a separate output category alongside the not-found error. Concretely: the stderr output is limited to the standard target-resolution error (and any unrelated warnings that would be emitted regardless of the flat-script sibling). There is no additional warning/notice/advisory line whose subject is the loose flat-script layout (the `.loopx/loose-script.sh` file itself is not mentioned in any extra category of output beyond, at most, the routine "target not found" message). Prose-level phrase matching is intentionally avoided — the check targets the presence of a distinct migration-warning output category, not specific wording. This is the flat-script counterpart to T-DISC-20c (legacy directory-script no-migration-warning), explicitly locking down the ADR-0003 consequence that no migration warnings are provided for any legacy layout. *(Spec 5.1)*
@@ -708,11 +1248,12 @@ Within `run`, `-h` / `--help` is a full short-circuit: when present, loopx shows
 - **T-DISC-12**: All top-level files with supported extensions inside a workflow are discovered as scripts. `.loopx/ralph/` contains `index.sh`, `check-ready.sh`, `setup.ts`. `loopx run -n 1 ralph:check-ready` runs `check-ready.sh`. `loopx run -n 1 ralph:setup` runs `setup.ts`. Assert via marker files. *(Spec 2.1, 5.1)*
 - **T-DISC-13**: Script name is the base name without extension. `.loopx/ralph/my-check.ts` → script name is `my-check`. `loopx run -n 1 ralph:my-check` runs it. *(Spec 2.1)*
 - **T-DISC-14**: Files in subdirectories within a workflow are NOT discovered. `.loopx/ralph/lib/helpers.ts` exists. `loopx run -n 1 ralph:helpers` fails. The `lib/` subdirectory is ignored during script discovery. *(Spec 2.1, 5.1)*
-- **T-DISC-14b**: Files in workflow subdirectories are usable internally by workflow scripts, even though they are invisible to loopx discovery. Create `.loopx/ralph/index.ts` that imports `./lib/helpers.ts` (e.g., `import { greet } from "./lib/helpers.ts"`) and uses the imported value in its output. Create `.loopx/ralph/lib/helpers.ts` exporting a function (e.g., `export function greet() { return "hello from helpers"; }`). `loopx run -n 1 ralph` succeeds and the output contains the value from `helpers.ts`. Additionally assert that `loopx run -n 1 ralph:helpers` fails (the subdirectory file is not a discovered script). This tests both halves of the Spec 2.1 statement that subdirectory files are "invisible to loopx and available for internal use by the workflow's scripts" — T-DISC-14 and T-DISC-14a cover "invisible," but not the positive "available for internal use" half. *(Spec 2.1, 5.1)*
+- **T-DISC-14b**: Files in workflow subdirectories are usable internally by workflow scripts, even though they are invisible to loopx discovery. Create `.loopx/ralph/index.ts` that imports `./lib/helpers.ts` (e.g., `import { greet } from "./lib/helpers.ts"`) and calls `output({ result: greet() })` with the imported value. Create `.loopx/ralph/lib/helpers.ts` exporting a function (e.g., `export function greet() { return "hello from helpers"; }`). Observe via `runPromise("ralph", { maxIterations: 1, cwd: project.dir })` — SPEC 7.1 specifies that the CLI never prints `result` to stdout, so the programmatic API is the correct observation surface for yielded `Output.result`. Assert: (a) the returned array's single `Output` has `result === "hello from helpers"` (proving the helper was successfully imported and its return value reached the yielded output), and (b) additionally, a direct `runCLI(["run", "-n", "1", "ralph:helpers"])` invocation exits non-zero (the subdirectory file is not a discovered script). This tests both halves of the Spec 2.1 statement that subdirectory files are "invisible to loopx and available for internal use by the workflow's scripts" — T-DISC-14 and T-DISC-14a cover "invisible," but not the positive "available for internal use" half. *(Spec 2.1, 5.1, 7.1)*
 - **T-DISC-14a**: Nested invalid files inside a workflow do not trigger fatal validation. `.loopx/ralph/index.sh` plus `.loopx/ralph/lib/-bad.ts` (invalid script name) and `.loopx/ralph/lib/check.sh` + `.loopx/ralph/lib/check.ts` (same-base-name collision). `loopx run -n 1 ralph` succeeds (exit code 0). The nested files in `lib/` are not discovered and therefore not validated — invalid names and collisions in subdirectories do not trigger fatal validation errors. This is the runtime counterpart to T-INST-64a (which covers the same scenario at install time). *(Spec 2.1, 5.1)*
 - **T-DISC-15**: Non-script files inside a workflow are allowed and ignored. `.loopx/ralph/` contains `index.ts`, `schema.json`, `README.md`. The non-script files do not cause warnings. `loopx run -n 1 ralph` works. *(Spec 2.1)*
 - **T-DISC-15a**: Config-style file with a supported extension is discovered as a script (no exclusion mechanism). `.loopx/ralph/` contains `index.ts` and `eslint.config.js`. Discovery treats `eslint.config.js` as a script with base name `eslint.config`. The dot in `eslint.config` violates the name restriction pattern `[a-zA-Z0-9_][a-zA-Z0-9_-]*`. `loopx run ralph` fails (exit code 1) due to global validation catching the invalid script name. *(Spec 2.1, 5.3)*
 - **T-DISC-15b**: Same setup as T-DISC-15a but via `loopx run -h`. The invalid script name `eslint.config` is reported as a non-fatal warning on stderr. Assert that the warning text contains the offending script name. Help still exits 0. This locks down the ADR-0003 rule that there is no exclusion mechanism — every top-level file with a supported extension is a discovered script, even config-style files. *(Spec 2.1, 5.3, 11.2)*
+- **T-DISC-15c**: Uppercase script extensions (`.SH`, `.TS`, `.JS`) are not supported — they do not match the lowercase-only supported-extension set (`.sh`, `.ts`, `.js`) and are therefore not discovered as scripts, and a subdirectory whose only supported-extension-shaped files are uppercase is **not a discovered workflow at all** (SPEC 5.1: "A subdirectory is a workflow if it contains at least one top-level file ... with a supported extension"). SPEC 2.1 / 5.1 enumerate the supported script extensions in lowercase form; the rule is case-sensitive (extensions are filename-suffix matches under POSIX, where filenames are case-sensitive — `index.SH` and `index.sh` are distinct files). Set up `.loopx/ralph/` containing a single file `index.SH` (uppercase extension only, no lowercase counterpart) alongside a valid sibling workflow `.loopx/other/index.sh` (so `.loopx/` itself discovers at least one workflow and the run does not short-circuit on "missing `.loopx/`"). Run `loopx run -n 1 ralph` via the CLI. Assert: (a) exit code 1 — not because `ralph` has no `index` script, but because `ralph` is not a discovered workflow at all (the only file in `.loopx/ralph/` has an unsupported extension, so the subdirectory fails the "contains at least one top-level file with a supported extension" workflow-detection rule and is silently ignored during discovery), (b) stderr surfaces a **missing-workflow / workflow-not-found** error referring to `ralph` (the exact wording is implementation-defined; the test does not pin a specific phrase but does require the failure category to be missing-workflow — **not** a missing-default-entry-point / missing-`index` error, and **not** a script-execution error), and (c) `index.SH` did not run (no marker file). Companion case: also run a variant with `.loopx/ralph/index.SH` **plus** `.loopx/ralph/index.sh` (both files present) — in this case `ralph` **is** a discovered workflow (because `index.sh` has a supported extension), only `index.sh` is discovered and runs, and `index.SH` is silently ignored (no warning, no name-collision warning, since collisions are checked across the *recognized* extension set only). This pins down case-sensitive extension matching, which a buggy implementation that lowercased filenames before extension matching (a common bug under macOS where the underlying filesystem is sometimes case-insensitive but the extension-matching logic should not be) would fail. **Conditional on a case-sensitive filesystem** — on case-insensitive filesystems (e.g., default macOS HFS+ / APFS) the two filenames cannot coexist, so the companion case is skipped; the single-`.SH` case is runnable on either filesystem because the file simply does not match the supported extension set. *(Spec 2.1, 5.1)*
 - **T-DISC-16**: Workflow directory with no top-level supported script files — only supported-extension files in subdirectories (e.g., `.loopx/ralph/lib/helpers.ts` exists but no `.loopx/ralph/*.{sh,js,jsx,ts,tsx}`) — is not recognized as a valid workflow. *(Spec 2.1, 5.1)*
 
 #### Default Entry Point
@@ -732,6 +1273,8 @@ Within `run`, `-h` / `--help` is a full short-circuit: when present, loopx shows
 - **T-DISC-22**: Same-base-name collision in one workflow is fatal for any target in any workflow. `.loopx/ralph/check.sh` and `.loopx/ralph/check.ts` exist, `.loopx/other/index.sh` is valid. `loopx run -n 1 other` still fails because global validation catches ralph's collision. *(Spec 5.2, 5.4)*
 - **T-DISC-23**: Same base names in **different** workflows are allowed. `.loopx/ralph/check.sh` and `.loopx/other/check.ts` coexist without collision. Both `loopx run -n 1 ralph:check` and `loopx run -n 1 other:check` succeed. *(Spec 5.2)*
 - **T-DISC-24**: Non-conflicting scripts within the same workflow → no error. `.loopx/ralph/alpha.sh` and `.loopx/ralph/beta.ts` coexist. *(Spec 5.2)*
+- **T-DISC-24a**: Same-base-name collision immunity for unsupported `.mjs` extension. SPEC 5.2's name-collision rule applies to **discovered** scripts only, and SPEC 2.1 / T-DISC-06 / T-DISC-07a establish that `.mjs` files are not discovered as scripts. A workflow containing `.loopx/ralph/check.ts` (a discovered script) plus `.loopx/ralph/check.mjs` (an unsupported-extension sibling sharing the same base name) must therefore **not** be flagged as a collision — `check.mjs` was never a discovery candidate, so there is no second `check` script to collide with. T-DISC-21 / T-DISC-21a cover the genuine same-base collision (two **discovered** extensions); T-DISC-07a covers `.mjs` non-discovery in the absence of a same-base sibling. This test pins down the intersection: same-base sibling + unsupported extension ≠ collision. Set up `.loopx/ralph/check.ts` (a discovered script that writes a marker file and emits `{"stop":true}`) and `.loopx/ralph/check.mjs` (any content — its content is irrelevant since it is never discovered). Run `loopx run -n 1 ralph:check`. Assert: (a) exit code 0, (b) the marker file exists (`check.ts` ran — not blocked by a spurious collision), (c) stderr contains no collision warning or error referencing `check.mjs` (the `.mjs` file is silently ignored, not flagged as a same-base conflict per the SPEC 5.2 collision rule's "discovered scripts" scope), and (d) `loopx run -n 1 ralph:check` resolves to `check.ts` deterministically — a buggy implementation that extension-fold-matched on base name (so `check.mjs` and `check.ts` were both treated as `check`) would either reject install with a same-base-collision error or pick one extension non-deterministically, both of which fail this test. *(Spec 2.1, 5.1, 5.2)*
+- **T-DISC-24b**: Same-base-name collision immunity for unsupported `.cjs` extension. `.cjs` counterpart to T-DISC-24a — same fixture pattern (`.loopx/ralph/check.ts` + `.loopx/ralph/check.cjs`), same assertions: `ralph:check` runs `check.ts`, no collision flag for `check.cjs`. T-DISC-07b covers `.cjs` non-discovery in isolation; this test pins down the same-base-sibling case for `.cjs` to mirror T-DISC-24a's `.mjs` coverage. Together with T-DISC-24a, this closes the unsupported-extension same-base-collision-immunity coverage for both `.mjs` and `.cjs`. *(Spec 2.1, 5.1, 5.2)*
 
 #### Workflow and Script Naming
 
@@ -745,6 +1288,9 @@ Within `run`, `-h` / `--help` is a full short-circuit: when present, loopx shows
 - **T-DISC-30**: Script name `check-ready` (hyphen in middle) → valid. *(Spec 5.3)*
 - **T-DISC-30a**: Script name `1start` (digit first) → valid per `[a-zA-Z0-9_]`. *(Spec 5.3)*
 - **T-DISC-30b**: Script name `42` (all digits) → valid. *(Spec 5.3)*
+- **T-DISC-30c**: Uppercase workflow name is valid and runnable. SPEC 5.3's name pattern `[a-zA-Z0-9_][a-zA-Z0-9_-]*` explicitly allows uppercase ASCII letters — the existing T-DISC-25 / T-DISC-26 / T-DISC-26a / T-DISC-26b coverage exercises hyphenated, underscore, and digit-first forms, but not uppercase positives. Set up `.loopx/MyWorkflow/index.sh` (mixed-case workflow name, starting with an uppercase letter) that writes a marker file on execution. Run `loopx run -n 1 MyWorkflow` via the CLI. Assert: (a) exit code 0, (b) the marker file exists (proving the workflow was discovered and `index.sh` ran), and (c) stderr contains no validation warnings for the workflow name. An implementation that lowercased workflow names during validation — or that treated the name pattern as case-insensitive and folded before matching — would fail to find `MyWorkflow` when the user typed it as `MyWorkflow` (under a case-sensitive filesystem). *(Spec 5.3, 2.1)*
+- **T-DISC-30d**: Uppercase script base name is valid and targetable via a qualified `workflow:Script` target. Set up `.loopx/ralph/CheckReady.sh` (a non-`index` script with a mixed-case base name) alongside `.loopx/ralph/index.sh` (the default entry point, present so the workflow is discovered without ambiguity and the target is explicitly the uppercase one). `CheckReady.sh` writes a marker file on execution and then emits `{ "stop": true }` via `$LOOPX_BIN output --stop`. Run `loopx run -n 1 "ralph:CheckReady"` via the CLI. Assert: (a) exit code 0, (b) the marker file exists (proving `ralph:CheckReady` was the resolved target and the script ran — not `ralph:index`), and (c) stderr contains no validation warnings for the script name. This is the script-name counterpart to T-DISC-30c, pinning down that uppercase script base names are accepted by both the name-pattern validator and the qualified-target parser. *(Spec 5.3, 2.1, 4.1)*
+- **T-DISC-30e**: Underscore-prefix script base name is valid and targetable. SPEC 5.3's name pattern `[a-zA-Z0-9_][a-zA-Z0-9_-]*` explicitly allows `_` as the first character. Workflow-name underscore is covered by T-DISC-26 (`.loopx/_underscore/index.sh`), and digit-first / all-digit / uppercase script names are covered by T-DISC-30a / T-DISC-30b / T-DISC-30d, but underscore-prefix script base names are not directly covered. A buggy validator that only accepted alphanumeric starts (`[a-zA-Z0-9]`) would silently reject `_check.sh` while still passing the digit-first / uppercase positive tests. Set up `.loopx/ralph/_check.sh` (a non-`index` script with a leading underscore) alongside `.loopx/ralph/index.sh` (the default entry point, present so the workflow is discovered cleanly and the underscore script is explicitly targeted). `_check.sh` writes a marker file on execution and emits `{"stop":true}`. Run `loopx run -n 1 "ralph:_check"` via the CLI. Assert: (a) exit code 0, (b) the marker file exists (proving `ralph:_check` was the resolved target and ran — not `ralph:index`), and (c) stderr contains no validation warnings for the script name. *(Spec 5.3, 2.1, 4.1)*
 - **T-DISC-31**: Script name with `:` → error. The `:` is explicitly disallowed in both workflow and script names. *(Spec 5.3)*
 - **T-DISC-32**: Workflow name with `:` → error. *(Spec 5.3)*
 
@@ -771,6 +1317,8 @@ Within `run`, `-h` / `--help` is a full short-circuit: when present, loopx shows
 - **T-DISC-40g**: Same fixture as T-DISC-40f under `loopx run -h`. Assert `-bad-link` is neither listed in the discovered-workflows output nor warned about on stderr. Only `ralph` appears. This is the help-mode counterpart to T-DISC-40f, and the invalid-name symlink variant of T-DISC-40b (valid-name symlink to non-workflow ignored in help). *(Spec 5.1, 5.3, 11.2)*
 - **T-DISC-40h**: Symlinked workflow directory with a valid alias name whose target's basename is invalid. Create a valid workflow directory at `/tmp/-bad-real-workflow/` (with `index.sh`), then symlink `.loopx/goodalias → /tmp/-bad-real-workflow/`. Also set up a valid workflow `.loopx/ralph/index.sh`. Assert: (a) `loopx run -n 1 goodalias` succeeds and runs the script (marker file written), and (b) `loopx run -h` lists `goodalias` without any warning about `-bad-real-workflow` on stderr. Validation uses only the symlink's own name (`goodalias`), and the target directory's basename (`-bad-real-workflow`) is completely ignored. Existing tests prove alias names are used (T-DISC-39) and invalid alias names fail (T-DISC-40c), but they do not prove that an invalid target basename is ignored — this test closes that gap. *(Spec 5.1, 5.3, 11.2)*
 - **T-DISC-40i**: Symlinked script file with a valid alias basename whose target file's basename is invalid. Create `.loopx/ralph/index.sh` and a symlink `.loopx/ralph/goodcheck.sh → /tmp/-bad-real-script.sh` (where the target file exists and is executable). Assert: (a) `loopx run -n 1 ralph:goodcheck` succeeds and runs the symlinked script (marker file written), and (b) `loopx run -h` lists `goodcheck` under `ralph` without any warning about `-bad-real-script` on stderr. This is the script-level counterpart to T-DISC-40h. Existing tests prove alias basenames are used (T-DISC-40) and invalid alias basenames fail (T-DISC-40d), but they do not prove that an invalid target basename is ignored — this test closes that gap. *(Spec 5.1, 5.3, 11.2)*
+- **T-DISC-40j**: A symlink inside `.loopx/` whose target is a **regular file** is not a workflow. SPEC 5.1 "Symlink policy" says symlinks are followed to determine entry types — if the resolved target is not a directory, the entry is not a workflow. Create a regular file outside `.loopx/` (e.g., `/tmp/not-a-dir.txt` containing `"hello"`), then symlink `.loopx/foo → /tmp/not-a-dir.txt`. Also set up a valid workflow `.loopx/ralph/index.sh`. Assert: (a) `loopx run -n 1 ralph` succeeds (the bad symlink does not break sibling discovery), (b) `loopx run foo` fails (not found as a workflow — the symlink resolves to a file, so the entry is not a workflow directory), and (c) no warning is emitted about `foo` on stderr, and (d) `loopx run -h` lists `ralph` but does not list or warn about `foo`. Workflow detection rules apply after symlink resolution; a symlink to a non-directory is not a workflow and the invalid alias name is never validated. *(Spec 5.1, 11.2)*
+- **T-DISC-40k**: A symlink inside a workflow directory whose target is a **directory** is not a script. SPEC 5.1 says scripts are top-level files with supported extensions; after symlink resolution the entry must be a file, not a directory. Create a real directory outside `.loopx/` (e.g., `/tmp/not-a-script-dir/` containing `README.md`), then set up `.loopx/ralph/index.sh` plus a symlink `.loopx/ralph/check.sh → /tmp/not-a-script-dir/`. Assert: (a) `loopx run -n 1 ralph` (bare — default entry) succeeds, running `index.sh` (the bogus `check.sh` symlink does not break discovery of siblings), (b) `loopx run -n 1 ralph:check` fails (not found as a script — the symlink resolves to a directory, so the entry is not a script file), and (c) `loopx run -h` lists `ralph` with `index` as its script but does not list `check` under `ralph` and does not warn about it on stderr. A buggy implementation that enumerated `.sh` entries without checking their resolved file type would wrongly list `check` here. *(Spec 5.1, 11.2)*
 
 #### Discovery Caching
 
@@ -778,6 +1326,10 @@ Within `run`, `-h` / `--help` is a full short-circuit: when present, loopx shows
 - **T-DISC-42**: During a loop, modify the content of an already-discovered script between iterations. Assert the new content takes effect on the next iteration (since the file is re-read from disk). *(Spec 5.1)*
 - **T-DISC-42a**: During a multi-iteration loop, an already-discovered script is removed (deleted from disk) between iterations. On the next iteration that would execute this script, loopx fails at spawn time. Assert loopx exits with code 1. *(Spec 5.1, 7.2)*
 - **T-DISC-42b**: During a multi-iteration loop, an already-discovered script is renamed between iterations (rename variant of T-DISC-42a). Create a workflow with `index.sh` (emits goto to `check`) and `check.sh`. After the first iteration discovers and caches `check.sh`, rename it to `check-new.sh` before the next iteration. The cached path for `check` still points to the original `check.sh`, which no longer exists. Assert loopx fails at spawn time with exit code 1. This covers the "removed or renamed" language in Spec 5.1. *(Spec 5.1, 7.2)*
+- **T-DISC-42d**: `run()` (generator) counterpart to T-DISC-42a — mid-loop removed script surfaces as a spawn failure on the generator surface. Same fixture as T-DISC-42a: `.loopx/ralph/index.sh` emits goto to `check`; `.loopx/ralph/check.sh` exists at loop start. Call `run("ralph", { maxIterations: 3 })` and iterate. Between the first and second `next()` call, `rm .loopx/ralph/check.sh`. Continue iterating. Assert: (a) the first yielded Output is from `index.sh` (with goto to `check`), (b) the next `next()` call (which would spawn `check`) throws a spawn-failure error — not a missing-target / discovery error, since discovery happened at loop start and cached `check.sh`'s path, (c) no `Output` is yielded for the failed spawn, and (d) any previously yielded Outputs remain consumed. Additionally assert that `LOOPX_TMPDIR` cleanup ran before the throw (the tmpdir no longer exists under `os.tmpdir()`). This is the programmatic-API counterpart to T-DISC-42a — SPEC 5.1 / 7.2's "spawn failure after tmpdir creation" contract must hold identically on the `run()` generator surface. *(Spec 5.1, 7.2, 9.1, 9.3)*
+- **T-DISC-42e**: `runPromise()` counterpart to T-DISC-42a — mid-loop removed script surfaces as a promise rejection on the promise surface. Same fixture as T-DISC-42a / T-DISC-42d, but it is difficult to externally coordinate a mid-run `rm` against `runPromise()` because `runPromise()` buffers outputs internally. Use an in-loop self-delete: `.loopx/ralph/index.sh` emits goto to `check` only on its first iteration (counter-gated); also `rm`s `check.sh` as part of its own execution before emitting the goto. Call `runPromise("ralph", { maxIterations: 3 })`. Assert: the promise rejects with a spawn-failure error, the error is raised before any yield from `check.sh` would be collected (so the resolved-array path is not taken), and `LOOPX_TMPDIR` cleanup ran before the rejection. This is the `runPromise` counterpart to T-DISC-42a / T-DISC-42d — per SPEC 9.3, partial outputs are not available via `runPromise()`, but the rejection contract must still hold. *(Spec 5.1, 7.2, 9.2, 9.3)*
+- **T-DISC-42f**: `run()` (generator) counterpart to T-DISC-42b — mid-loop **renamed** script surfaces as a spawn failure. Same fixture as T-DISC-42b: `.loopx/ralph/index.sh` emits goto to `check`; `.loopx/ralph/check.sh` exists at loop start. Call `run("ralph", { maxIterations: 3 })` and iterate. Between the first and second `next()` call, `mv .loopx/ralph/check.sh .loopx/ralph/check-new.sh`. Continue iterating. Assert: the second `next()` throws a spawn-failure error (the cached path for `check` still points to `check.sh`, which no longer exists after the rename), no Output is yielded for the failed spawn, and `LOOPX_TMPDIR` cleanup ran before the throw. This is the rename-variant programmatic-API counterpart to T-DISC-42b. *(Spec 5.1, 7.2, 9.1, 9.3)*
+- **T-DISC-42g**: `runPromise()` counterpart to T-DISC-42b — mid-loop renamed script surfaces as a promise rejection. Uses the same in-loop self-rename pattern as T-DISC-42e: `.loopx/ralph/index.sh` emits goto to `check` only on its first iteration; also `mv`s `check.sh` to `check-new.sh` as part of its own execution before emitting the goto. Call `runPromise("ralph", { maxIterations: 3 })`. Assert: the promise rejects with a spawn-failure error, and `LOOPX_TMPDIR` cleanup ran before the rejection. This is the rename-variant `runPromise` counterpart to T-DISC-42b / T-DISC-42f. *(Spec 5.1, 7.2, 9.2, 9.3)*
 - **T-DISC-42c**: During a multi-iteration loop, a new script file is added to an already-discovered workflow between iterations. Start with `.loopx/ralph/index.sh` only — the `index.sh` script creates `.loopx/ralph/new-step.sh` on its first execution (detected via a marker file), then on the second iteration emits `goto: "new-step"`. The `goto` targets a script that was not present at loop start → error (not in cached discovery), exit code 1. This is the "new script in existing workflow" counterpart to T-DISC-41 (new workflow added mid-loop). *(Spec 5.1)*
 
 #### Validation Scope
@@ -785,8 +1337,8 @@ Within `run`, `-h` / `--help` is a full short-circuit: when present, loopx shows
 - **T-DISC-43**: `loopx version` works when `.loopx/` doesn't exist. *(Spec 5.4)*
 - **T-DISC-44**: `loopx env set X Y` when `.loopx/` doesn't exist → exits 0. *(Spec 5.4)*
 - **T-DISC-45**: `loopx output --result "x"` when `.loopx/` doesn't exist → exits 0. *(Spec 5.4)*
-- **T-DISC-46**: `loopx version` when `.loopx/` exists and contains name collisions → exits 0 with version string. No validation warnings. *(Spec 5.4)*
-- **T-DISC-47**: `loopx install <source>` when `.loopx/` exists and contains collisions → install succeeds for a non-colliding workflow. Install validates the source workflows, not all of `.loopx/`. *(Spec 5.4, 10.5)*
+- **T-DISC-46**: `loopx version` when `.loopx/` exists and contains a broken tree (same-base-name collision, invalid workflow name, and invalid script name) → exits 0 with version string. No validation warnings. This proves `version` does not validate any `.loopx/` failure mode, not just collisions. *(Spec 5.4)*
+- **T-DISC-47**: `loopx install <source>` when `.loopx/` exists and contains a broken sibling tree (same-base-name collision, invalid workflow name, invalid script name) → install succeeds for a non-colliding workflow. Install validates the source workflows and the target path, not all of `.loopx/`. *(Spec 5.4, 10.5)*
 - **T-DISC-47a**: Invalid script name in a sibling workflow is fatal in normal run mode. Create `.loopx/ralph/index.sh` (valid) and `.loopx/broken/-bad.sh` (invalid script name). `loopx run ralph` → exits with code 1. Global validation catches the invalid name in the sibling workflow before execution begins. This is the normal-run-mode counterpart to T-CLI-22d (`-n 0`) and the name-restriction analogue to T-DISC-22 (sibling collision). *(Spec 5.3, 5.4)*
 - **T-DISC-47b**: Invalid workflow name in a sibling workflow is fatal in normal run mode. Create `.loopx/good/index.sh` (valid) and `.loopx/-bad-workflow/index.sh` (invalid workflow name). `loopx run good` → exits with code 1. Global validation catches the invalid workflow name in the sibling before execution begins. This is the workflow-name counterpart to T-DISC-47a (sibling invalid script name) and the normal-run-mode counterpart to T-CLI-120 (invalid workflow name non-fatal in `run -h`). *(Spec 5.3, 5.4)*
 
@@ -801,10 +1353,11 @@ Within `run`, `-h` / `--help` is a full short-circuit: when present, loopx shows
 
 #### Working Directory
 
-- **T-EXEC-01**: Script in workflow `.loopx/ralph/index.sh` writes `$PWD` to a marker file. Assert the marker file content equals the absolute path of `.loopx/ralph/` (the workflow directory), **not** the project root. *(Spec 6.1)*
-- **T-EXEC-02**: A different workflow `.loopx/other/index.sh` writes `$PWD` to a marker file. Assert it equals `.loopx/other/`. *(Spec 6.1)*
-- **T-EXEC-03**: Script writes `$LOOPX_PROJECT_ROOT` to a marker file. Assert marker content equals the invocation directory (project root), not the workflow directory. *(Spec 6.1)*
-- **T-EXEC-03a**: `LOOPX_PROJECT_ROOT` is preserved across cross-workflow goto. Script `ralph:index` outputs `goto:"other:check"`. Script `other:check` writes `$LOOPX_PROJECT_ROOT` to a marker file. Assert marker content equals the project root directory, not `.loopx/other/`. This pins down the one remaining env/cwd interaction not covered by T-EXEC-03 (normal execution), T-EXEC-16b (cross-workflow cwd switch), and T-EXEC-04b (cross-workflow `LOOPX_WORKFLOW` update): that `LOOPX_PROJECT_ROOT` stays the original project root after a cross-workflow transition, even though cwd changes to the target workflow directory. *(Spec 6.1, 8.3)*
+- **T-EXEC-01**: Script in workflow `.loopx/ralph/index.sh` observes its working directory via the `write-cwd-to-file` fixture (`/bin/pwd -P`, not `$PWD` — Spec 6.1 explicitly rules `$PWD` non-authoritative). Assert the marker file content equals the **project root directory** (the CLI invocation cwd), **not** the workflow directory. Per Spec 6.1, every script spawn has project-root cwd; the workflow-relative path is exposed via `LOOPX_WORKFLOW_DIR`, not cwd. *(Spec 6.1)*
+- **T-EXEC-02**: A different workflow `.loopx/other/index.sh` observes its working directory via `write-cwd-to-file`. Assert the marker file content equals the **project root** (same as T-EXEC-01). Multiple workflows running in the same run all spawn with project-root cwd — cwd does not differ by workflow. *(Spec 6.1)*
+- **T-EXEC-03**: Script writes `$LOOPX_PROJECT_ROOT` to a marker file. Assert marker content equals the invocation directory (project root). In the current spec, cwd already equals the project root for every spawn (T-EXEC-01/02), so `LOOPX_PROJECT_ROOT` is redundant for child-relative reads in the child's own working directory — but the variable is still injected for scripts that `cd` elsewhere or hand paths to tools that don't inherit cwd. *(Spec 6.1, 8.3)*
+- **T-EXEC-03a**: `LOOPX_PROJECT_ROOT` is preserved across cross-workflow goto. Script `ralph:index` outputs `goto:"other:check"`. Script `other:check` writes `$LOOPX_PROJECT_ROOT` to a marker file. Assert marker content equals the project root directory, unchanged from the starting workflow. Cross-workflow `goto` changes `LOOPX_WORKFLOW` and `LOOPX_WORKFLOW_DIR` (see T-EXEC-04b and the `LOOPX_WORKFLOW_DIR` tests below) but **does not change cwd** — cwd is the project root for every spawn in the run. This pins down that `LOOPX_PROJECT_ROOT` stays the original project root after a cross-workflow transition, consistent with cwd staying at the project root. *(Spec 6.1, 8.3)*
+- **T-EXEC-03b**: Child `cd` does not leak across spawns. Set up `.loopx/ralph/index.sh` to `cd /tmp` (or any real directory outside the project root, e.g., `cd "$(mktemp -d)"`) and then emit `{"goto":"check"}`. Set up `.loopx/ralph/check.sh` to observe its own cwd via `/bin/pwd -P` into a marker and emit `{"stop":true}`. Run `loopx run -n 2 ralph`. Assert: (a) exit code 0, (b) the `check.sh` cwd marker equals the project root — **not** `/tmp` or whichever directory the first script `cd`'d into. Per SPEC 6.1, "Scripts remain free to `cd` (Bash) or `process.chdir()` (JS/TS) within the child process; such changes are scoped to that child and do not affect later spawns, which always start at project-root cwd." This is the spawn-isolation counterpart to T-EXEC-01 / T-EXEC-02 (which verify project-root cwd on a single spawn); a buggy implementation that reused the spawn cwd from the child's final state would fail this test. *(Spec 6.1)*
 - **T-EXEC-04**: `LOOPX_WORKFLOW` is injected correctly. Script writes `$LOOPX_WORKFLOW` to a marker file. Assert marker content equals the workflow name (e.g., `ralph`). *(Spec 8.3)*
 - **T-EXEC-04a**: `LOOPX_WORKFLOW` overrides inherited/env-file values. Set `LOOPX_WORKFLOW=fake` in global env and spawn with `LOOPX_WORKFLOW=fake` in the process environment. Script writes `$LOOPX_WORKFLOW` to a marker file. Assert marker contains the real workflow name, not `"fake"`. *(Spec 8.3)*
 - **T-EXEC-04b**: Cross-workflow goto updates `LOOPX_WORKFLOW`. Script `ralph:index` outputs `goto:"other:check"`. Script `other:check` writes `$LOOPX_WORKFLOW` to a marker file. Assert marker contains `other`, not `ralph`. *(Spec 8.3)*
@@ -815,6 +1368,8 @@ Within `run`, `-h` / `--help` is a full short-circuit: when present, loopx shows
 - **T-EXEC-05**: A `.sh` script runs successfully and its stdout is captured as structured output. Observe via `runPromise("ralph", { maxIterations: 1 })`: the yielded Output contains the expected `result`. *(Spec 6.2)*
 - **T-EXEC-06**: A `.sh` script's stderr appears on the CLI's stderr (pass-through). *(Spec 6.2)*
 - **T-EXEC-07**: A `.sh` script that lacks `#!/bin/bash` still runs (loopx invokes via `/bin/bash` explicitly). Assert actual execution via marker file. *(Spec 6.2)*
+- **T-EXEC-07a**: A `.sh` script **without the executable bit** still runs. SPEC 6.2 says loopx invokes Bash scripts as `/bin/bash <script>`, so the execute permission on the script file is not required — the read permission needed by `/bin/bash` to read the script is sufficient. Create `.loopx/ralph/index.sh` with mode `0644` (readable but not executable — explicitly `chmod 0644` after creation, overriding any helper default that sets the execute bit). The script body emits `{"stop":true}` and writes a marker file on execution. Run `loopx run -n 1 ralph`. Assert: (a) exit code 0, (b) the marker file was written (the script actually ran despite the missing executable bit), (c) `stat` of the script file still reports mode `0644` (loopx did not silently chmod it). T-EXEC-07 covers the missing-shebang case; this test covers the missing-executable-bit case — an implementation that used `exec`/`spawn` with `argv[0] = <script>` (which requires `+x` on the script) rather than `/bin/bash <script>` would fail this test. *(Spec 6.2)*
+- **T-EXEC-07b**: Bash scripts are invoked via the **absolute path `/bin/bash`**, not via `bash` resolved from `PATH`. SPEC 6.2 normatively says "Bash scripts (`.sh`) are executed as child processes via `/bin/bash`." T-EXEC-07 (missing shebang) and T-EXEC-07a (missing executable bit) prove "loopx does not direct-exec the script file"; together they rule out `argv[0] = <script>`-style invocation but do **not** rule out an implementation that resolves `bash` from `PATH` (e.g., `spawn("bash", [<script>])`) instead of using the absolute `/bin/bash` form. A `PATH`-resolved `bash` would still satisfy T-EXEC-07 / T-EXEC-07a (missing shebang and missing `+x` are runner-side properties, independent of how `bash` itself is located), but on a host whose `PATH` exposes a different `bash` first, behavior would diverge from the SPEC's absolute-path contract. This test pins down absolute `/bin/bash` invocation. Set up `.loopx/ralph/index.sh` (any valid script that emits `{"stop":true}` and writes a real-bash marker file). Create a throw-away directory containing a fake `bash` shim: an executable that writes a distinctive sentinel marker to a separate file (e.g., `printf 'FAKE-BASH-INVOKED' > "$FAKE_BASH_MARKER"`) and exits non-zero (e.g., `exit 99`). Spawn loopx with that throw-away directory **prepended** to `PATH` (so `bash` from `PATH` resolves to the fake) but with the real `/bin/bash` available at its absolute path. Run `loopx run -n 1 ralph`. Assert: (a) exit code 0 — loopx used `/bin/bash`, not the fake `bash` (which would have caused exit 99 / non-zero from a script-runner failure), (b) the **fake-bash sentinel marker file does NOT exist** — `bash` from `PATH` was never invoked, (c) the **real-bash marker file from `index.sh` exists** — the actual script body ran, proving real `/bin/bash` executed it. An implementation that did `spawn("bash", [<script>])` instead of `spawn("/bin/bash", [<script>])` would invoke the fake shim, write the fake-bash sentinel, and exit non-zero — failing all three assertions. The test is conditional on `/bin/bash` existing as an absolute file (true on POSIX hosts in CI) and is the platform-policy counterpart to T-EXEC-07 / T-EXEC-07a. *(Spec 6.2)*
 
 #### JS/TS Scripts
 
@@ -826,14 +1381,31 @@ Within `run`, `-h` / `--help` is a full short-circuit: when present, loopx shows
 - **T-EXEC-13**: JS/TS script can use TypeScript type annotations (verifies tsx handles TS syntax under Node.js). `[Node]` *(Spec 6.3)*
 - **T-EXEC-13b**: JS/TS script can use TypeScript type annotations under Bun. `[Bun]` *(Spec 6.3)*
 - **T-EXEC-13a**: A `.js` script that uses `require()` (CJS) fails with an error. CJS is not supported. *(Spec 6.3)*
-- **T-EXEC-14**: `[Bun]` When running under Bun, JS/TS scripts are executed via Bun's native runtime, not `tsx`. *(Spec 6.3)*
+- **T-EXEC-13c**: A `.js` script that uses `module.exports = {...}` (CJS) fails at execution time. SPEC 6.3 forbids all CommonJS syntax in loopx scripts, not just `require()`. The fixture is a script with an ESM-allowed shape (e.g., an `import` from `"loopx"`) plus a `module.exports = { value: "x" }` assignment — under ESM module evaluation, `module` is not a binding and the reference fails. Assert the script exits non-zero and loopx exits with code 1. This extends T-EXEC-13a (`require()`) to the second CommonJS-syntax failure branch enumerated in SPEC 6.3. *(Spec 6.3)*
+- **T-EXEC-13d**: A `.js` script that uses `exports.foo = ...` (CJS) fails at execution time. SPEC 6.3 forbids `exports` as a top-level binding, the third of the three CommonJS forms enumerated (`require()`, `module.exports`, `exports`). Fixture is a script with an ESM-allowed shape plus an `exports.value = "x"` assignment — under ESM, `exports` is not a binding and the reference fails. Assert the script exits non-zero and loopx exits with code 1. Together with T-EXEC-13a (`require()`) and T-EXEC-13c (`module.exports`), this completes CommonJS-syntax-rejection coverage across all three forms SPEC 6.3 enumerates. *(Spec 6.3)*
+- **T-EXEC-13e**: A `.ts` script that uses `require()` (CJS) fails at execution time. SPEC 6.3 forbids CommonJS syntax in **all** JS/TS scripts — `.sh` aside, every supported script extension (`.js`, `.ts`, `.jsx`, `.tsx`) runs under ESM semantics. Existing T-EXEC-13a covers the `.js` case of `require()`; this test pins down the `.ts` counterpart so a buggy implementation cannot silently route `.ts` through a CJS-compatible loader while enforcing ESM-only for `.js`. Fixture is a `.ts` script with an ESM-allowed shape (e.g., an `import` from `"loopx"`) plus a `require("node:fs")` call — under ESM, `require` is not a binding and the reference fails. Assert the script exits non-zero and loopx exits with code 1. This extends T-EXEC-13a (`require()` in `.js`) to the `.ts` execution path, closing the "`.ts` accidentally CJS-compatible" branch. *(Spec 6.3)*
+- **T-EXEC-13f**: A `.jsx` script that uses `require()` (CJS) fails at execution time. SPEC 6.3 forbids CommonJS syntax in **all** JS/TS script extensions — `.js`, `.jsx`, `.ts`, `.tsx`. T-EXEC-13a covers `.js`, T-EXEC-13e covers `.ts`; this test pins down `.jsx` so a buggy implementation cannot silently route `.jsx` through a CJS-compatible loader while enforcing ESM-only for the other extensions. Fixture is a `.jsx` script with an ESM-allowed shape (e.g., an `import` from `"loopx"`) plus a `require("node:fs")` call. Assert the script exits non-zero and loopx exits with code 1. *(Spec 6.3)*
+- **T-EXEC-13g**: A `.tsx` script that uses `require()` (CJS) fails at execution time. SPEC 6.3 forbids CommonJS syntax in **all** JS/TS script extensions. T-EXEC-13a covers `.js`, T-EXEC-13e covers `.ts`, T-EXEC-13f covers `.jsx`; this test pins down `.tsx` so all four supported JS/TS extensions are covered for the `require()` rejection case. Fixture is a `.tsx` script with an ESM-allowed shape (e.g., an `import` from `"loopx"`) plus a `require("node:fs")` call. Assert the script exits non-zero and loopx exits with code 1. Together with T-EXEC-13a / T-EXEC-13e / T-EXEC-13f, this completes `require()`-rejection coverage across the four JS/TS extensions; T-EXEC-13c / T-EXEC-13d cover the `module.exports` and `exports` branches on `.js`. *(Spec 6.3)*
+- **T-EXEC-13h**: A `.ts` script that uses `module.exports = {...}` (CJS) fails at execution time. SPEC 6.3 forbids `module.exports` as a top-level binding in all JS/TS script extensions. T-EXEC-13c covers the `.js` case; this test extends to `.ts`. Fixture is a `.ts` script with an ESM-allowed shape (e.g., an `import` from `"loopx"`) plus a `module.exports = { value: "x" }` assignment — under ESM module evaluation, `module` is not a binding and the reference fails. Assert the script exits non-zero and loopx exits with code 1. *(Spec 6.3)*
+- **T-EXEC-13i**: A `.jsx` script that uses `module.exports = {...}` (CJS) fails at execution time. Same shape as T-EXEC-13h but for the `.jsx` extension. Fixture is a `.jsx` script with an ESM-allowed shape plus a `module.exports = { value: "x" }` assignment. Assert the script exits non-zero and loopx exits with code 1. *(Spec 6.3)*
+- **T-EXEC-13j**: A `.tsx` script that uses `module.exports = {...}` (CJS) fails at execution time. Same shape as T-EXEC-13h but for the `.tsx` extension. Fixture is a `.tsx` script with an ESM-allowed shape plus a `module.exports = { value: "x" }` assignment. Assert the script exits non-zero and loopx exits with code 1. Together with T-EXEC-13c (`.js`) / T-EXEC-13h (`.ts`) / T-EXEC-13i (`.jsx`), this completes `module.exports`-rejection coverage across all four JS/TS extensions. *(Spec 6.3)*
+- **T-EXEC-13k**: A `.ts` script that uses `exports.foo = ...` (CJS) fails at execution time. SPEC 6.3 forbids `exports` as a top-level binding in all JS/TS script extensions. T-EXEC-13d covers the `.js` case; this test extends to `.ts`. Fixture is a `.ts` script with an ESM-allowed shape plus an `exports.value = "x"` assignment — under ESM, `exports` is not a binding and the reference fails. Assert the script exits non-zero and loopx exits with code 1. *(Spec 6.3)*
+- **T-EXEC-13l**: A `.jsx` script that uses `exports.foo = ...` (CJS) fails at execution time. Same shape as T-EXEC-13k but for the `.jsx` extension. Fixture is a `.jsx` script with an ESM-allowed shape plus an `exports.value = "x"` assignment. Assert the script exits non-zero and loopx exits with code 1. *(Spec 6.3)*
+- **T-EXEC-13m**: A `.tsx` script that uses `exports.foo = ...` (CJS) fails at execution time. Same shape as T-EXEC-13k but for the `.tsx` extension. Fixture is a `.tsx` script with an ESM-allowed shape plus an `exports.value = "x"` assignment. Assert the script exits non-zero and loopx exits with code 1. Together with T-EXEC-13d (`.js`) / T-EXEC-13k (`.ts`) / T-EXEC-13l (`.jsx`), this completes `exports.foo`-rejection coverage across all four JS/TS extensions. With T-EXEC-13a / T-EXEC-13e / T-EXEC-13f / T-EXEC-13g (the `require()` matrix) and T-EXEC-13c / T-EXEC-13h / T-EXEC-13i / T-EXEC-13j (the `module.exports` matrix) and this `exports` matrix, the SPEC 6.3 "CommonJS syntax in a loopx script is an error" rule is fully covered across all three CJS forms × all four JS/TS extensions. *(Spec 6.3)*
+- **T-EXEC-14**: `[Bun]` When running under Bun, JS/TS scripts are executed via Bun's native runtime, not `tsx`. Use a JS/TS fixture that records a Bun-only runtime marker (for example `typeof Bun !== "undefined"` or `Bun.version`) before calling `output(...)`. Assert the marker indicates Bun is the active runtime. A Node/tsx-based implementation would not expose the `Bun` global and would fail this test. *(Spec 6.3)*
 
 #### Workflow-Local Dependencies
 
 - **T-EXEC-15**: Workflow with its own `node_modules/` can import from local dependencies. Setup: create a workflow with a local dependency in `node_modules/`. Script writes a marker file confirming the import succeeded. *(Spec 2.1)*
-- **T-EXEC-16**: Workflow CWD is the workflow directory. TS script writes `process.cwd()` to a marker file. Assert marker content matches the workflow's directory path (e.g., `.loopx/ralph/`). *(Spec 6.1)*
+- **T-EXEC-15a**: `loopx run` does **not** auto-install workflow dependencies, even when `package.json` is present and `node_modules/` is missing. Set up `.loopx/ralph/` with `index.sh` (bash, outputs `{"stop":true}`) and `package.json` (valid, declares any dependency — e.g., `{ "dependencies": { "some-pkg": "*" } }`) but NO `node_modules/` directory. Use `withFakeNpm({ exitCode: 0, logFile })` to observe any npm invocation. Run `loopx run -n 1 ralph` via the CLI. Assert: (a) exit code 0, (b) the shim log records **zero** `npm` invocations — `run` does not trigger the auto-install step, (c) `.loopx/ralph/node_modules/` still does not exist (loopx did not run `npm install`), and (d) the script's marker file exists (execution succeeded). Per SPEC 2.1: "At runtime, loopx does **not** re-install dependencies — `loopx run` does not invoke `npm install` on a missing `node_modules/`." This is the runtime counterpart to the install-time auto-install coverage (T-INST-110 block); the auto-install seam is exclusive to `loopx install`. *(Spec 2.1, 10.10)*
+- **T-EXEC-15b**: `runPromise()` also does not auto-install workflow dependencies. Same fixture as T-EXEC-15a. Call `runPromise("ralph", { maxIterations: 1 })` via `runAPIDriver`. Assert: (a) the promise resolves with one output, (b) the fake-npm shim log records zero invocations, (c) `.loopx/ralph/node_modules/` does not exist. This is the programmatic-API counterpart to T-EXEC-15a — the "no runtime auto-install" rule must hold on every run surface, not just the CLI. *(Spec 2.1, 9.2)*
+- **T-EXEC-15c**: `run()` (generator surface) also does not auto-install workflow dependencies. Same fixture as T-EXEC-15a / T-EXEC-15b: `.loopx/ralph/` with `index.sh` (bash, outputs `{"stop":true}`) and a `package.json` declaring any dependency, no `node_modules/` directory. Use `withFakeNpm({ exitCode: 0, logFile })` to observe any npm invocation. Drive `const gen = run("ralph", { maxIterations: 1 }); for await (const _ of gen) { /* drain */ }` via `runAPIDriverLive` (or the equivalent live-generator harness used by other `run()` tests). Assert: (a) the generator settles cleanly (no throw — the script ran and emitted `stop: true`), (b) the fake-npm shim log records **zero** invocations — `run()` does not trigger the auto-install step, and (c) `.loopx/ralph/node_modules/` still does not exist. Per SPEC 2.1: "At runtime, loopx does **not** re-install dependencies — `loopx run` does not invoke `npm install` on a missing `node_modules/`." T-EXEC-15a covers the CLI surface and T-EXEC-15b covers `runPromise()`; this test closes the third API-surface gap by exercising the `run()` generator surface, completing the "no runtime auto-install" coverage across all three run surfaces (CLI, `runPromise()`, `run()`). A buggy implementation that gated auto-install on the run surface (e.g., enabled it under `run()` but disabled it under the CLI / `runPromise()`) would pass T-EXEC-15a / T-EXEC-15b but fail this test. *(Spec 2.1, 9.1, 10.10)*
+- **T-EXEC-16**: Script cwd is the project root in JS/TS runtimes too. TS script uses the `observe-cwd-ts` fixture (`process.cwd()` via `fs.writeFileSync`). Assert marker content matches the **project root** directory (not the workflow directory). Directory identity (device/inode) is guaranteed to match the project root; the exact string spelling may be the runtime-canonicalized (`getcwd(3)`) form per Spec 6.1 "Directory identity vs. string spelling". If the project root was supplied via CLI, the string comparison should be against `process.cwd()` observed by loopx at invocation. *(Spec 6.1)*
 - **T-EXEC-16a**: Workflow that imports a package not present in its `node_modules/` — the script fails with a module resolution error from the active runtime, and loopx exits with code 1. *(Spec 2.1)*
-- **T-EXEC-16b**: Cross-workflow goto preserves per-workflow cwd. Set up `ralph:index` to output `goto:"other:check"`. Script `other:check` writes `$PWD` (bash) or `process.cwd()` (TS) to a marker file. Assert the marker content equals the absolute path of `.loopx/other/`, not `.loopx/ralph/`. This proves cwd switches to the target workflow's directory on cross-workflow goto — locking down ADR-0003 behavior that each workflow's scripts always execute in their own workflow directory, even when reached via cross-workflow transition. *(Spec 6.1, 2.2)*
+- **T-EXEC-16b**: Cross-workflow goto preserves project-root cwd (does **not** switch cwd). Set up `ralph:index` to output `goto:"other:check"`. Script `other:check` observes its cwd via `write-cwd-to-file` (bash) or `observe-cwd-ts` (TS). Assert the marker content equals the **project root** directory — the same cwd the starting workflow had — not `.loopx/other/`. Per Spec 6.1, cross-workflow `goto` changes `LOOPX_WORKFLOW` / `LOOPX_WORKFLOW_DIR` but not cwd; every spawn in the run uses project-root cwd. A separate `observe-env` marker on `LOOPX_WORKFLOW_DIR` confirms that the workflow-relative path surface did switch to `.loopx/other/` — cwd and `LOOPX_WORKFLOW_DIR` are independent. *(Spec 6.1)*
+- **T-EXEC-16c**: JS/TS `process.chdir()` does not leak across spawns. Set up `.loopx/ralph/index.ts` to call `process.chdir("/tmp")` (or any real directory outside the project root, e.g., `process.chdir(os.tmpdir())`) and then `output({ goto: "check" })`. Set up `.loopx/ralph/check.ts` to observe its own `process.cwd()` via `observe-cwd-ts` into a marker and `output({ stop: true })`. Run via `runPromise("ralph", { maxIterations: 2 })` (or `loopx run -n 2 ralph`). Assert: (a) execution completes successfully, (b) the `check.ts` cwd marker has the same directory identity as the project root — **not** `/tmp` or whichever directory `process.chdir()` set. Per SPEC 6.1, `process.chdir()` changes are scoped to the child process and do not affect later spawns, which always start at project-root cwd. This is the JS/TS counterpart to T-EXEC-03b (bash `cd` isolation). A separate `forEachRuntime` invocation proves the isolation holds under both Node/tsx and Bun. *(Spec 6.1)*
+- **T-EXEC-03c**: Bash `cd` does not leak across **loop reset** (no-`goto` reset to the starting target). T-EXEC-03b covers `cd` isolation across an explicit intra-workflow `goto`; this test pins down the same isolation guarantee on the loop-reset path, where the cycle ends without a `goto` and the next iteration restarts the starting target. SPEC 6.1's "later spawns always start at project-root cwd" is normatively independent of how the next spawn is reached (goto vs. reset); a buggy implementation could correctly reset cwd on the goto path while leaking the prior child's `cd`-changed cwd on the loop-reset path (e.g., by deriving the spawn cwd from the goto-target lookup and falling back to the previous child's cwd when no goto was emitted). Set up `.loopx/ralph/index.sh` to (1) maintain an iteration counter at `$LOOPX_TMPDIR/iter` (initialize to `0` if absent, then increment), (2) on iteration 1, `cd /tmp` (or any real directory outside the project root, e.g., `cd "$(mktemp -d)"`) and emit empty output (no `goto`, no `stop`) so the cycle resets and the loop returns to `ralph:index`, and (3) on iteration 2, observe its own cwd via `/bin/pwd -P` into a marker and emit `{"stop":true}`. Run `loopx run -n 2 ralph`. Assert: (a) exit code 0, (b) the iteration-2 cwd marker equals the **project root** (directory identity matches via `stat`) — **not** `/tmp` or whichever directory iteration 1 `cd`'d into. Per SPEC 6.1, "Scripts remain free to `cd` (Bash) or `process.chdir()` (JS/TS) within the child process; such changes are scoped to that child and do not affect later spawns, which always start at project-root cwd." T-EXEC-03b covers the goto-driven next-spawn reset; this test covers the no-goto loop-reset path explicitly. *(Spec 6.1, 2.2)*
+- **T-EXEC-16d**: JS/TS `process.chdir()` does not leak across **loop reset** (no-`goto` reset to the starting target). JS/TS counterpart to T-EXEC-03c, mirroring how T-EXEC-16c is the JS/TS counterpart to T-EXEC-03b. SPEC 6.1's "later spawns always start at project-root cwd" applies symmetrically across runtime axes; a buggy implementation could correctly reset cwd across goto on both runtimes while leaking the prior child's `process.chdir()`-changed cwd on the loop-reset path (e.g., by reusing the previous child's reported cwd as the next spawn cwd default). Set up `.loopx/ralph/index.ts` to (1) maintain an iteration counter at `$LOOPX_TMPDIR/iter` (initialize to `0` if absent, then increment via `fs.writeFileSync`), (2) on iteration 1, `process.chdir("/tmp")` (or any real directory outside the project root, e.g., `process.chdir(os.tmpdir())`) and then exit normally without writing anything to stdout (per SPEC 2.3, empty stdout is treated as `{ result: "" }` — no `goto`, no `stop` — so the cycle resets per SPEC 2.2; the script must **not** call `output({})`, which throws per SPEC 6.4 and is covered by T-MOD-07), and (3) on iteration 2, observe its own `process.cwd()` via `observe-cwd-ts` into a marker and `output({ stop: true })`. Run via `runPromise("ralph", { maxIterations: 2 })` (or `loopx run -n 2 ralph`). Assert: (a) execution completes successfully, (b) the iteration-2 cwd marker has the same directory identity as the project root — **not** `/tmp` or whichever directory iteration 1's `process.chdir()` set. A separate `forEachRuntime` invocation proves the isolation holds under both Node/tsx and Bun. T-EXEC-16c covers the goto-driven next-spawn reset on the JS/TS surface; this test covers the no-goto loop-reset path on the same surface. Together with T-EXEC-03c (Bash loop-reset) this closes the loop-reset cwd-isolation gap across both script runtimes. *(Spec 6.1, 2.2, 2.3)*
 
 ### 4.5 Structured Output Parsing
 
@@ -849,6 +1421,7 @@ All fixture scripts live inside a workflow (e.g., `.loopx/test/index.sh`). The `
 - **T-PARSE-02**: Script outputs `{"goto":"next"}` → loopx transitions to script `next` (within the same workflow). *(Spec 2.3)*
 - **T-PARSE-03**: Script outputs `{"stop":true}` → loop halts, exit code 0. *(Spec 2.3)*
 - **T-PARSE-04**: Script outputs `{"result":"x","goto":"next","stop":true}` → stop takes priority, loop halts. *(Spec 2.3)*
+- **T-PARSE-04a**: `stop: true` beats an **invalid** `goto` — no goto-validation error is surfaced. Per SPEC 2.3 "Field precedence": `stop: true` takes priority over `goto`. T-PARSE-04 proves the precedence with a *valid* goto; this test pins down the stronger claim that the precedence applies *before* goto-target validation, so a malformed or nonexistent goto never triggers its error path when `stop: true` is set. Create a workflow whose `index` script outputs `{"stop":true,"goto":"a:b:c"}` (the `a:b:c` target is invalid per SPEC 4.1 — multiple colons). Run `loopx run ralph` (CLI) and also observe via `runPromise("ralph")`. Assert: (a) CLI exit code 0 (loop halted cleanly via `stop: true`), (b) stderr contains no goto-validation error (neither the multiple-colon error nor a missing-workflow/missing-script error), (c) `runPromise` resolves with one Output containing `stop: true` (and does not reject), and (d) no second iteration runs (verify via counter file that the script ran exactly once). This test covers the end-to-end "stop beats goto" precedence claim that T-PARSE-04 does not exercise (T-PARSE-04's valid goto would also be suppressed, but that does not prove validation itself was short-circuited). *(Spec 2.3, 4.1)*
 - **T-PARSE-05**: Script outputs `{"result":"x","extra":"ignored"}`. Assert via `runPromise("test", { maxIterations: 1 })`: yielded Output has `result: "x"` and no `extra` property. *(Spec 2.3)*
 
 #### Fallback to Raw Result
@@ -862,6 +1435,7 @@ All fixture scripts live inside a workflow (e.g., `.loopx/test/index.sh`). The `
 - **T-PARSE-12**: Script outputs `not json at all`. Assert yielded Output has `result: "not json at all"`. *(Spec 2.3)*
 - **T-PARSE-12a**: Raw fallback preserves exact stdout including trailing newline. Script outputs `hello\n`. Assert yielded Output has `result: "hello\n"`. *(Spec 2.3)*
 - **T-PARSE-13**: Script produces empty stdout. Assert yielded Output is `{ result: "" }`. *(Spec 2.3)*
+- **T-PARSE-13a**: Whitespace-only stdout falls back to raw with the whitespace bytes preserved. SPEC 2.3 raw-fallback rule: when stdout does not parse as a JSON object containing at least one known field, the entire stdout becomes `result`. T-PARSE-12 / T-PARSE-12a cover non-JSON text and trailing-newline preservation; T-PARSE-13 covers empty stdout. The whitespace-only case (e.g., three spaces) is a distinct boundary: it's not empty, it's not parseable as JSON, and a buggy implementation that trimmed stdout before raw-fallback could collapse it to `""` (matching T-PARSE-13's outcome) or trigger an empty-object short-circuit. Use `stdout-writer` (or an equivalent fixture) to write exactly three space characters to stdout (no JSON, no newline). Observe via `runPromise("ralph", { maxIterations: 1 })`: assert the yielded Output is exactly `{ result: "   " }` (three spaces preserved byte-for-byte). Fuzz coverage (F-PARSE-04) likely catches whitespace-only inputs incidentally, but pinning this case down explicitly closes a manual-traceability gap. *(Spec 2.3)*
 
 #### Type Coercion
 
@@ -869,6 +1443,7 @@ All fixture scripts live inside a workflow (e.g., `.loopx/test/index.sh`). The `
 - **T-PARSE-15**: `{"result": true}`. Assert yielded Output has `result: "true"`. *(Spec 2.3)*
 - **T-PARSE-16**: `{"result": {"nested": "obj"}}`. Assert yielded Output has `result: "[object Object]"`. *(Spec 2.3)*
 - **T-PARSE-17**: `{"result": null}`. Assert yielded Output has `result: "null"`. *(Spec 2.3)*
+- **T-PARSE-17a**: `{"result": [1,2]}` (array result value). Assert yielded Output has `result: "1,2"` (coerced via `String(value)` — `String([1,2])` is `"1,2"`). SPEC 2.3: "If `result` is present but not a string, it is coerced via `String(value)`." T-PARSE-14–17 cover number, boolean, object, and null variants of the coercion rule; F-PARSE-* fuzz tests probably cover arrays incidentally, but adding an explicit manual test improves traceability and pins down the array case in a way that does not depend on fuzz-input generation reaching it. *(Spec 2.3)*
 - **T-PARSE-18**: `{"goto": 42}` (goto is not a string). Assert yielded Output is exactly `{}`. *(Spec 2.3)*
 - **T-PARSE-19**: `{"goto": true}`. Assert yielded Output is exactly `{}`. *(Spec 2.3)*
 - **T-PARSE-20**: `{"goto": null}`. Assert yielded Output is exactly `{}`. *(Spec 2.3)*
@@ -914,9 +1489,11 @@ All fixture scripts live inside a workflow (e.g., `.loopx/test/index.sh`). The `
 - **T-LOOP-11**: `ralph:index` outputs `{"result":"payload","goto":"reader"}`. `ralph:reader` reads stdin and outputs the received value as its result. Observe via `runPromise("ralph", { maxIterations: 2 })`: the second yielded Output has `result: "payload"`. *(Spec 6.6)*
 - **T-LOOP-12**: `ralph:index` outputs `{"goto":"reader"}` (no result). `ralph:reader` reads stdin → empty string. *(Spec 2.3, 6.6)*
 - **T-LOOP-13**: `ralph:index` outputs `{"result":"payload"}` (no goto). Loop resets to index. Index reads stdin → empty string (result not piped on reset). *(Spec 6.6)*
+- **T-LOOP-13a**: Cross-workflow reset clears stdin even when the cross-workflow chain produced a `result`. SPEC 2.2 / 6.6 specify that on loop reset (no `goto` in the previous output), the starting target receives empty stdin **regardless of any `result` value in the previous output** — and this rule is keyed on the loop-reset semantic, not on whether the previous script lived in the starting workflow or a cross-workflow goto destination. T-LOOP-13 covers single-workflow reset (`ralph:index` → no goto → `ralph:index` again with empty stdin); this test extends the rule to a **cross-workflow** reset path, where the no-goto-output script that drives the reset lives in a different workflow than the starting target. A buggy implementation that only enforced the empty-stdin rule when the no-goto script was in the starting workflow (and incidentally piped `result` on reset when crossing workflow boundaries) would pass T-LOOP-13 and fail this test. Set up two workflows: `.loopx/alpha/index.sh` and `.loopx/beta/step.sh`. `alpha:index` first emits `{"goto":"beta:step"}` on its first execution, then on subsequent executions reads stdin via `cat-stdin` and outputs the received bytes as its `result` (so the harness can observe what the second `alpha:index` actually saw on stdin). `beta:step` outputs `{"result":"payload"}` with **no `goto`** (this triggers the loop reset back to `alpha:index`). Run via `runPromise("alpha", { maxIterations: 3 })` so the harness can observe all three iterations' yielded outputs in order. Assert the yielded outputs in order are: (a) iteration 1 — `alpha:index`'s first output is `{ goto: "beta:step" }` (no `result` payload to observe — the iteration-1 output is the goto trigger), (b) iteration 2 — `beta:step`'s output is `{ result: "payload" }` (proving the cross-workflow goto chain produced the `result` that should **not** be piped on reset), and (c) iteration 3 — `alpha:index`'s second output's `result` is the empty string `""` (proving stdin on the reset iteration was empty, **not** `"payload"` from `beta:step`'s output). A buggy implementation that piped `beta:step`'s `result` to the reset iteration's `alpha:index` stdin would surface `"payload"` as iteration 3's `result`, failing assertion (c). T-LOOP-13 (single-workflow) plus T-LOOP-13a (cross-workflow) close the SPEC 6.6 reset-clears-stdin contract across both workflow-locality variants. *(Spec 2.2, 6.6, 6.7)*
 - **T-LOOP-14**: First iteration receives empty stdin. *(Spec 6.7)*
 - **T-LOOP-15**: Chain A → goto B with result → B → goto C with result → C reads stdin and gets B's result, not A's. *(Spec 6.6)*
 - **T-LOOP-15a**: Cross-workflow stdin piping. `ralph:index` outputs `{"result":"cross-payload","goto":"other:reader"}`. `other:reader` reads stdin and outputs the received value as its result. Observe via `runPromise("ralph", { maxIterations: 2 })`: the second yielded Output has `result: "cross-payload"`. Proves `result` crosses the workflow boundary via stdin. *(Spec 6.6, 2.2)*
+- **T-LOOP-15b**: Coerced non-string `result` is piped via stdin when `goto` is present — specifically, the coerced **`String(value)` bytes**, not the JSON representation. SPEC 2.3 specifies that when `result` is a non-string value, the parser coerces it to a string via `String(value)`; SPEC 6.6 specifies that when `result` is present alongside `goto`, `result` is piped to the next script via stdin. These two rules are each covered independently (T-PARSE-* for coercion, T-LOOP-11 for piping with a string `result`), but not their composition: a buggy implementation that piped coerced values as their JSON form or that skipped the piping when the value came from coercion would violate the spec. **The test must use a value whose `String(value)` bytes differ from its JSON representation**, otherwise the assertion cannot distinguish "coerced then piped" from "piped as JSON bytes." A naive number-based test (`result: 42`) fails this distinguishing requirement because `String(42) === "42"` and `JSON.stringify(42) === "42"` — the byte sequences are identical. Instead, use a **JSON object** value, which produces distinctive bytes under `String()`: `ralph:index` outputs `{"result":{"x":1},"goto":"reader"}` (non-string `result` — a JSON object). Per SPEC 2.3, the parser computes `String({x:1})` which yields `"[object Object]"` (15 bytes). `ralph:reader` reads stdin via `cat-stdin`-equivalent and outputs the received bytes as its own string `result`. Observe via `runPromise("ralph", { maxIterations: 2 })`: (a) the first yielded `Output` has `result: "[object Object]"` (coerced from the JSON object via `String()`), and (b) the second yielded `Output` has `result: "[object Object]"` — `reader`'s stdin was exactly the coerced string `"[object Object]"`, byte-for-byte (no trailing newline unless the parser adds one, which it does not per SPEC 2.3 / 6.6). Assert both values are byte-identical to `"[object Object]"`. A buggy implementation that piped the literal JSON form (`{"x":1}`, 7 bytes) would fail the byte comparison because the bytes `[object Object]` and `{"x":1}` are disjoint. An implementation that dropped the piping for coerced values (so `reader` received empty stdin and emitted `result: ""`) would also fail. An alternative distinguishing fixture using an array value (`{"result":[1,2],"goto":"reader"}` → `String([1,2]) === "1,2"` vs `JSON.stringify([1,2]) === "[1,2]"`) is equally valid; the choice of object vs array is free as long as the value's `String()` bytes differ from its JSON bytes. *(Spec 2.3, 6.6)*
 
 #### Goto Semantics — Intra-Workflow
 
@@ -957,17 +1534,28 @@ All fixture scripts live inside a workflow (e.g., `.loopx/test/index.sh`). The `
 - **T-LOOP-22**: Script fails on iteration 3 of 5 (`-n 5`). Assert exactly 3 iterations ran. *(Spec 7.2)*
 - **T-LOOP-23**: Script's stderr output on failure is visible on CLI stderr. *(Spec 7.2)*
 - **T-LOOP-24**: Script's stdout on failure is NOT parsed as structured output. Observe via `run("ralph")`: the generator throws without yielding an Output for that iteration. *(Spec 7.2)*
+- **T-LOOP-24a**: CLI — script's stdout on non-zero exit is neither parsed as structured output nor leaked to the CLI's stdout stream. SPEC 6.2 / 6.3 / 7.2 specify that script stdout is captured (not pass-through) and that on non-zero exit it is not parsed as structured output; SPEC 7.1 separately specifies that the CLI itself never prints `result` to its own stdout. Together these imply: when a script writes structured-looking content to stdout, then writes a marker to stderr, then exits non-zero, the CLI must (a) not parse the stdout, (b) not pass the stdout through to its own stdout stream, and (c) still surface the stderr marker to the user. T-LOOP-24 covers the "no Output yielded" half via the programmatic API; this test pins down the CLI-stdout-silence half. Set up `.loopx/ralph/index.sh` that writes `'{"stop":true}\n'` (or any other structured-looking JSON payload) to stdout via `printf '%s\n' '{"stop":true}'`, writes a distinctive marker `'STDERR-MARKER-T-LOOP-24A: script about to fail with exit 1'` to stderr via `printf 'STDERR-MARKER-T-LOOP-24A: script about to fail with exit 1\n' >&2`, then `exit 1`. Run via `runCLI(["run", "-n", "1", "ralph"])`. Assert: (a) the CLI exit code is 1 (script-failure exit, not the would-be `stop: true` clean exit), (b) the CLI's captured **stdout is empty** byte-for-byte (no leaked structured-looking content; in particular, the literal string `{"stop":true}` is not present in stdout — proving stdout from a failed script was neither parsed nor passed through), (c) the CLI's captured **stderr contains the `STDERR-MARKER-T-LOOP-24A` line** (script stderr is forwarded to the user's terminal regardless of script exit code per SPEC 6.2 / 6.3). A buggy implementation that streamed script stdout through to the CLI's own stdout (rather than capturing it for parsing) would surface the JSON payload on the CLI stdout stream and fail (b); an implementation that parsed the stdout despite the non-zero exit and surfaced `stop: true` would exit 0 instead of 1 and fail (a). Together with T-LOOP-24 (programmatic surface), this closes the SPEC 6.2 / 6.3 / 7.2 stdout-capture / no-parse-on-failure contract on both the CLI and programmatic surfaces. *(Spec 6.2, 6.3, 7.1, 7.2)*
 
 #### Final Iteration Output
 
 - **T-LOOP-25**: `-n 2` with script producing `{"result":"iter-N"}`. Both iterations' outputs are observable via programmatic API. *(Spec 7.1)*
 
+#### Max-Iteration-Before-Goto Validation
+
+SPEC 7.1's basic-loop algorithm increments the iteration counter (step 9), then checks `stop` (step 10), then checks whether the `-n` / `maxIterations` limit has been reached (step 11: "If `-n` was specified and the iteration count has been reached: exit with code 0. The output from this final iteration is still yielded/observed before termination."), and **only after that** validates and executes `goto` (step 12). So on the iteration that hits the limit, an otherwise-invalid `goto` value must not surface a goto-validation error — the loop terminates before step 12 runs. These tests pin down that ordering.
+
+- **T-LOOP-44**: CLI — invalid `goto` on the final counted iteration does not surface a goto-validation error. Create `.loopx/ralph/index.sh` that outputs `{"goto":"a:b:c"}` (three-colon target — invalid per Spec 4.1's "multiple colons" rule). Run `loopx run -n 1 ralph`. Assert: (a) exit code 0 (not 1 for invalid goto), (b) stderr contains no goto-validation error for the `a:b:c` target, and (c) the `ralph:index` script ran (marker file asserts actual execution). The iteration counter hit the `-n 1` limit before the goto validation step; the final iteration's output is yielded/observed but the invalid goto never reaches validation. Complementary to T-LOOP-37 (invalid `a:b:c` goto with `-n` > 1, which must exit 1). *(Spec 7.1)*
+- **T-LOOP-45**: `runPromise` — invalid `goto` on the final counted iteration resolves, does not reject. Same fixture as T-LOOP-44 (`ralph:index` outputs `{"goto":"a:b:c"}`). Call `runPromise("ralph", { maxIterations: 1 })`. Assert: (a) the promise resolves (does not reject with a goto-validation error), (b) the resolved array has length 1 and the sole Output has `goto: "a:b:c"` (the value was parsed and yielded without validation being triggered), and (c) the `ralph:index` script ran (marker file). The ordering rule is identical across the CLI and programmatic surfaces. *(Spec 7.1, 9.2)*
+- **T-LOOP-46**: `run()` — invalid `goto` on the final counted iteration yields, then settles done without throwing. Same fixture as T-LOOP-44/T-LOOP-45. Drive: `const gen = run("ralph", { maxIterations: 1 }); const first = await gen.next(); const second = await gen.next();` Assert: (a) `first.done === false` and `first.value.goto === "a:b:c"` (the final iteration's output is yielded, not swallowed), (b) `second.done === true` and no error is thrown (the generator settles cleanly — no goto-validation error surfaces because the limit was reached before step 12), and (c) the `ralph:index` script ran exactly once (marker file). This is the generator-surface counterpart to T-LOOP-45; together the three tests pin down that the "check `-n` / `maxIterations` before validating `goto`" ordering holds across all three run surfaces. *(Spec 7.1, 9.1)*
+
 ### 4.7 Environment Variables
 
 **Spec refs:** 8.1–8.3
 
 All env tests use `withGlobalEnv` to isolate from the real user config.
 
+**Env-absence robustness (suite-wide harness rule).** Many tests across this suite assert that a particular environment variable is **absent** from the spawned script's `process.env` (or from the `npm install` child's env in the SPEC 10.10 surface). Examples include the `RunOptions.env` shape / precedence tests (`INHERITED`, `HIDDEN`, `NEWVAR`, …), the env-file-not-injected tests (`INJECTED_GLOBAL`, …), and the auto-install env-purity tests (T-INST-115's `INJECTED_GLOBAL` / `LOOPX_*` absence assertions). For every such assertion to be meaningful, the named variable must not be present in any of loopx's lower-tier env sources (the inherited `process.env` from the test runner, the global env file resolved via the test's isolated `XDG_CONFIG_HOME` / `HOME`, and the local env file the test loaded). Without that, an absence assertion can pass spuriously on a host where the variable happened to be unset and fail on a host where the developer's shell had it set — the assertion would be testing the host environment, not loopx's behavior. **Therefore: any test that asserts an environment variable is absent from the spawned script's env (or any env loopx forwards to a child) must either (a) use a unique per-test key that cannot plausibly be present in inherited env or in any env file the test loads (e.g., a clearly synthetic name like `LOOPX_TEST_ABSENCE_FOO`), or (b) explicitly scrub that key from all lower-tier env sources before invoking loopx — at minimum, `delete process.env.<KEY>` for the test runner's inherited env, and ensure neither the global nor local env file the test installs contains the key.** Tests that already follow this rule (e.g., T-INST-115's explicit scrubbing of `LOOPX_*` names from loopx's inherited environment before running) are correct as-written; tests whose descriptions assert absence without naming the scrubbing or per-test-uniqueness step are required to apply this rule at implementation time even when the description does not call it out explicitly. This is a test-correctness / flake-prevention rule, not a SPEC requirement.
+
 #### Global Env File
 
 - **T-ENV-01**: Variable set via `loopx env set` is available in a script. Use `write-env-to-file` fixture inside a workflow's `index.sh`. Assert the marker file contains the expected value. *(Spec 8.1, 8.3)*
@@ -980,6 +1568,7 @@ All env tests use `withGlobalEnv` to isolate from the real user config.
 - **T-ENV-05c**: Unreadable global env file with `loopx env list` → exits with code 1. **Conditional on `process.getuid() !== 0`.** *(Spec 8.1)*
 - **T-ENV-05d**: Unreadable global env file with `loopx env set` → exits with code 1. **Conditional on `process.getuid() !== 0`.** *(Spec 8.1)*
 - **T-ENV-05e**: Unreadable global env file with `loopx env remove` → exits with code 1. **Conditional on `process.getuid() !== 0`.** *(Spec 8.1)*
+- **T-ENV-05f**: Unreadable global env file under **normal-path `runPromise()`** (non-zero `maxIterations`) rejects. SPEC 8.1 / 9.2 / 9.3 specify that the unreadable global env-file failure is a pre-iteration error and surfaces via promise rejection on the `runPromise()` surface. T-ENV-05b covers the generic programmatic-API generator-side path; T-API-08l2 covers `runPromise()` only under `maxIterations: 0` (which is its own validation surface); the CLI-side coverage is in T-ENV-05a. None of these directly exercise normal nonzero-iteration `runPromise()` rejection on the unreadable-global-env path — a buggy implementation that gated unreadable-global-env handling specifically on `maxIterations === 0` (treating it as a pre-iteration validation step that runs only in the zero-iteration short-circuit) would pass T-API-08l2 but fail to reject under normal execution. Use `withGlobalEnv` to place a global env file with mode 000 (unreadable). Set up `.loopx/ralph/index.sh` (any valid script). Call `runPromise("ralph", { maxIterations: 1 })`. Assert: (a) the promise rejects with an unreadable-env-file error (the SPEC 8.1 unreadable-file failure surface, not a parser-shape error), (b) the workflow script did not run (no marker file), and (c) the rejection is observable via the standard promise-rejection path (not a synchronous throw at the call site). **Conditional on `process.getuid() !== 0`.** *(Spec 8.1, 9.2, 9.3)*
 
 #### Env File Parsing
 
@@ -988,6 +1577,7 @@ All env file parsing tests below use `writeEnvFileRaw` to write exact file conte
 - **T-ENV-06**: `writeEnvFileRaw(path, "KEY=VALUE\n")`. Assert marker contains `VALUE`. *(Spec 8.1)*
 - **T-ENV-07**: `writeEnvFileRaw(path, "# comment\nKEY=val\n")`. Assert `KEY=val`. *(Spec 8.1)*
 - **T-ENV-08**: Blank lines ignored, `KEY=val` loaded. *(Spec 8.1)*
+- **T-ENV-08a**: Whitespace-only lines (lines containing only spaces, tabs, or a mix) are treated as blank and ignored silently — no warning, no bogus key, and subsequent valid lines parse normally. SPEC 8.1 specifies that "A line containing only whitespace (for example, spaces and/or tabs, after removing the line terminator) is considered blank and is ignored silently without a warning." Use `writeEnvFileRaw(path, "   \n\t\t\nOK=fine\n")` — three spaces on line 1, two tabs on line 2, valid pair on line 3. Run a workflow observing `OK` via `observe-env`. Assert: (a) `OK=fine` is loaded normally (the whitespace-only lines do not poison subsequent valid lines), (b) no environment variable is set whose name is the empty string or whitespace (the parser does not synthesize a key from a whitespace-only line), and (c) **no warning is emitted on stderr for the two whitespace-only lines** — they are silently ignored, distinct from the warning-emitting "invalid key" / "no `=`" branches covered by T-ENV-15c / T-ENV-15d / T-ENV-15l. T-ENV-08 covers truly empty lines (`\n` between content); this test pins down that whitespace-only lines are equivalent to empty lines under SPEC 8.1's "blank line" definition. A buggy implementation that warned on whitespace-only lines (treating them as malformed non-key lines under a strict reading of the T-ENV-15l-style rules) would fail assertion (c). *(Spec 8.1)*
 - **T-ENV-09**: Duplicate keys: last occurrence wins. *(Spec 8.1)*
 - **T-ENV-10**: Double-quoted value → quotes stripped. *(Spec 8.1)*
 - **T-ENV-11**: Single-quoted value → quotes stripped. *(Spec 8.1)*
@@ -995,12 +1585,21 @@ All env file parsing tests below use `writeEnvFileRaw` to write exact file conte
 - **T-ENV-13**: Inline `#` is part of value. *(Spec 8.1)*
 - **T-ENV-14**: Trailing whitespace on value trimmed. *(Spec 8.1)*
 - **T-ENV-15**: `KEY = value` → invalid key (space before `=`). Warning on stderr. *(Spec 8.1)*
-- **T-ENV-15f**: `KEY= value` → leading space in value preserved. *(Spec 8.1)*
+- **T-ENV-15f**: `KEY= value` (whitespace immediately after `=`) is invalid and ignored with a warning. SPEC 8.1's "**No whitespace is permitted around `=`**" rule is the primary clause: "around `=`" means on either side. The second clause ("the value is everything after `=` ... (trimmed of trailing whitespace)") describes value extent after the line's surface form has satisfied the around-`=` rule; it does not override the rule. T-ENV-15 covers space before `=` and T-ENV-15j covers the tab-before-`=` variant; this test pins down the after-`=` side, which the key-pattern check does not catch. Use `writeEnvFileRaw(path, "KEY= value\nOK=fine\n")`. **Explicitly unset `KEY` in loopx's inherited environment before spawning**, so that a child's `process.env.KEY` being absent is attributable to the env-file line being dropped rather than to an inherited-env tier supplying a value. (Without this unset, the child could legitimately observe `KEY` from inherited process env — which would defeat the "`KEY` is absent" assertion as a test of the env-file-parser behavior.) Run a workflow observing `KEY` and `OK` via `observe-env`. Assert: (a) the parser emits a warning for the `KEY= value` line (same warning class as T-ENV-15 — whitespace around `=`), (b) `KEY` is **not** loaded (the `observe-env` marker records `{ "present": false }` for `KEY` — with inherited `KEY` unset, the absence is attributable to the parser-drop of the malformed line), and (c) `OK=fine` is loaded normally (the malformed line does not poison subsequent valid lines). An implementation that adopted the permissive reading (leading whitespace in value preserved) would load `KEY=" value"` and emit no warning, failing this test. *(Spec 8.1)*
 - **T-ENV-15a**: `KEY=` → empty value. Variable is present with empty string. *(Spec 8.1)*
 - **T-ENV-15b**: `KEY=a=b=c` → split on first `=`. *(Spec 8.1)*
 - **T-ENV-15c**: `1BAD=val` → invalid key, line ignored with warning. *(Spec 8.1)*
 - **T-ENV-15d**: `justtext` → malformed line, ignored with warning. *(Spec 8.1)*
 - **T-ENV-15e**: Unmatched quotes → literal preserved. *(Spec 8.1)*
+- **T-ENV-15h**: Leading whitespace before `#` is **not** a comment. SPEC 8.1 says "Lines starting with `#` are comments" — the "starting with" is positional, not "the first non-whitespace character is `#`". A line beginning with a space followed by `#` is therefore a malformed non-key line (no `=`), not a comment. Use `writeEnvFileRaw(path, "   # this is not a comment\nKEY=value\n")` (three leading spaces before `#`). Run a workflow observing `KEY`. Assert: (a) the parser warns the leading-space-`#` line as a malformed non-key line (same warning class as T-ENV-15d, since the line has no `=`), and (b) `KEY=value` is loaded normally. An implementation that trims leading whitespace before the comment check would silently drop the leading-`#` line instead of warning, and would pass this test only if the positional "starts with `#`" rule is honored. *(Spec 8.1)*
+- **T-ENV-15i**: Trailing whitespace after a quoted value is trimmed **before** quote stripping. SPEC 8.1 says values are "trimmed of trailing whitespace" and that quotes (optional) are stripped when the value "begins and ends with the same quote character." Apply order matters: if trailing whitespace were preserved, the value `"value"   ` (three trailing spaces after the closing quote) would not begin and end with the same quote character (it ends with a space), so the quote-stripping rule would not fire and the value would be treated literally as `"value"   ` (with outer quotes). The correct behavior is to trim trailing whitespace first, yielding `"value"`, then strip the matching outer quotes, yielding `value`. Use `writeEnvFileRaw(path, 'KEY="value"   \n')`. Run a workflow observing `KEY`. Assert the observed value is exactly `value` (no quote characters, no trailing whitespace). *(Spec 8.1)*
+- **T-ENV-15i-single**: Single-quoted-value variant of T-ENV-15i. SPEC 8.1's "begins and ends with the same quote character" rule applies to both `'…'` and `"…"`, and the trim-before-quote-strip ordering must be symmetric across the two quote characters. T-ENV-15i pins down the double-quoted case; this test pins down the single-quoted case, which a buggy implementation could special-case (e.g., apply trim-then-strip only to double quotes and apply strip-then-trim — or no strip — to single quotes). Use `writeEnvFileRaw(path, "KEY='value'   \n")` (single quotes around value, three trailing spaces after the closing quote). Run a workflow observing `KEY`. Assert the observed value is exactly `value` (no quote characters, no trailing whitespace). Together with T-ENV-15i this proves the trim-before-strip ordering is quote-character-agnostic. Fuzz coverage (F-ENV) likely catches this incidentally, but pinning the case down explicitly closes a manual-traceability gap. *(Spec 8.1)*
+- **T-ENV-15j**: Whitespace around a key before `=` is invalid. SPEC 8.1 says "No whitespace is permitted around `=`." This covers both sides — a tab or space in `KEY \t=value` or `KEY =value` must result in the line being rejected (invalid key name). T-ENV-15 covers space before `=`; this test pins down the tab variant. Use `writeEnvFileRaw(path, "KEY\t=value\n")` (literal tab before `=`). Run a workflow observing `KEY`. Assert: (a) the parser warns the line as invalid (the effective key `KEY<tab>` is not matched by the `[A-Za-z_][A-Za-z0-9_]*` key pattern), and (b) `KEY` is not loaded (no marker value). *(Spec 8.1)*
+- **T-ENV-15l**: Leading whitespace before a key is invalid and the line is ignored with a warning. SPEC 8.1's key pattern `[A-Za-z_][A-Za-z0-9_]*` requires the key to begin with an alphanumeric/underscore character, not whitespace. The combined effect with the "no whitespace around `=`" rule is that a line beginning with whitespace (followed by `KEY=value`) has an effective key of `<space>KEY` or `\tKEY`, which the key-pattern check rejects. T-ENV-15h already covers leading whitespace before `#` (malformed non-key line, no `=`); this test covers leading whitespace before a valid-shape `key=value`. Use `writeEnvFileRaw(path, " KEY=value\nOK=fine\n")` (single leading space before `KEY`). Run a workflow observing `KEY` and `OK`. Assert: (a) the parser emits a warning for the leading-whitespace line (same warning class as T-ENV-15 / T-ENV-15j), (b) `KEY` is not loaded, and (c) `OK=fine` is loaded normally. An implementation that trimmed leading whitespace on each line before applying the key pattern would silently accept ` KEY=value` and fail this test. *(Spec 8.1)*
+- **T-ENV-15m**: Lowercase env-file key is accepted. The SPEC 8.1 key pattern `[A-Za-z_][A-Za-z0-9_]*` explicitly allows lowercase — existing T-ENV-* tests primarily use uppercase `KEY` form, but not lowercase positives. Use `writeEnvFileRaw(path, "mykey=myval\n")`. Run a workflow observing `mykey`. Assert: (a) no warnings on stderr for this line, (b) `mykey` is loaded with value `"myval"`. Paired with T-SUB-11a (lowercase `env set`), this test closes the lowercase-key coverage gap at the env-file parse layer. An implementation that uppercase-folded keys before the pattern check (or required uppercase-first) would fail one or both. *(Spec 8.1)*
+- **T-ENV-15n**: Empty key (`=value`) is invalid and the line is ignored with a warning; following valid lines still parse. SPEC 8.1's key pattern `[A-Za-z_][A-Za-z0-9_]*` requires the key to have at least one character — an empty string preceding `=` does not match (`[A-Za-z_]` requires exactly one initial character, and the empty string contains zero characters). The `=value` case is therefore an "invalid key name" line per SPEC 8.1's key-validation paragraph and must be ignored with a warning. Existing invalid-key tests cover digit-first (`1BAD=val`, T-ENV-15c), no-`=` (`justtext`, T-ENV-15d), space-around-`=` (T-ENV-15 / T-ENV-15f / T-ENV-15j), and leading-whitespace (T-ENV-15l) — but the empty-key branch (`=value`) is the one remaining keyspace boundary not directly covered. A buggy parser that special-cased "lines with `=`" as automatically-key-shaped (without re-validating that the substring before `=` matches the key pattern) would silently accept an empty-key entry — for example, by storing it under the empty-string key, or by silently dropping it without a warning. Use `writeEnvFileRaw(path, "=ignored-value\nOK=fine\n")` (an empty-key line followed by a valid `OK=fine` line). **Explicitly unset the empty-string key in loopx's inherited environment if any tier could supply it** (in practice this is irrelevant on POSIX runtimes where empty-string env keys cannot be set via shell or `process.env`, but the test should not assume the empty-string key is unset by accident). Run a workflow observing both the empty-string key (e.g., `process.env[""]`) and `OK` via `observe-env`. Assert: (a) the parser emits exactly one warning for the empty-key line (same warning class as T-ENV-15c — invalid key name; the exact warning text is implementation-defined per SPEC 8.1, only that a single key-validation warning is emitted for the line), (b) the empty-string key is **not** loaded (the `observe-env` marker for `process.env[""]` records `{ "present": false }` — the line was dropped per the key-validation rule, not stored under the empty-string key), and (c) `OK=fine` is loaded normally with value `"fine"` (the malformed empty-key line did not poison subsequent valid lines — the parser is per-line and does not abort on a single invalid line). Together with T-ENV-15c (digit-first) and T-ENV-15d (no `=`), T-ENV-15j (tab around `=`), and T-ENV-15l (leading whitespace), this test closes coverage for the full SPEC 8.1 key-validation rejection enumeration on the env-file parse path. *(Spec 8.1)*
+- **T-ENV-15k**: CRLF line endings parse as if trailing `\r` were trailing whitespace. SPEC 8.1 says values are "trimmed of trailing whitespace," which includes the carriage return that CRLF-terminated files leave at the end of each line. An env file written on a CRLF platform (or any file saved with CRLF endings) should therefore parse cleanly. Use `writeEnvFileRaw(path, "KEY=value\r\nKEY2=\"quoted\"\r\n")` — two CRLF-terminated lines, with and without quotes. Run a workflow observing `KEY` and `KEY2` via `observe-env`. Assert: (a) `KEY` is loaded with value exactly `value` (no trailing `\r`), (b) `KEY2` is loaded with value exactly `quoted` (the trailing `\r` was trimmed before the quote-stripping pass, analogous to T-ENV-15i's "trim trailing whitespace before quote stripping" ordering), and (c) no warnings on stderr for these CRLF lines (they are well-formed after trailing-whitespace trimming). An implementation that treated `\r` as part of the value would produce `value\r` for `KEY` and `"quoted"\r` (with the quote-stripping rule not firing) for `KEY2`. *(Spec 8.1)*
+- **T-ENV-15g**: Actual multiline content inside a quoted value is **not** treated as a multiline value. Per SPEC 8.1 "No multiline value support" — loopx's `.env` parser is line-oriented; it does not join or escape across physical newlines, even when the quoted value's opening quote is not closed on the same line. Use `writeEnvFileRaw(path, 'KEY="line1\nline2"\n')` — the file contains two physical lines (`KEY="line1` and `line2"`). Run a workflow that observes `KEY` via `observe-env`. Assert: (a) the parser treats the two physical lines independently, (b) the resulting `KEY` (if recognized at all) has a single-line value — specifically, the opening quote on line 1 is unmatched on that line, so SPEC 8.1's "unmatched quotes → literal preserved" rule (already pinned by T-ENV-15e) applies to line 1 and `KEY` resolves to the literal `"line1` (with the leading quote preserved), and (c) line 2 (`line2"`) does not contain `=` on its own, so it is treated as a malformed / non-key line and is ignored with a warning on stderr — per SPEC 8.1's "lines without `=`" warning rule (already pinned by T-ENV-15d). Additionally assert (d) `KEY`'s observed value does **not** contain a `\n` byte — confirming the parser does not splice physical lines into a single multiline value. This is the multiline-content-in-file counterpart to T-ENV-12 (which pins down that `\n` as an escape sequence is treated literally, not as a newline) — T-ENV-12 covers the escape-sequence case, but not the case where the file itself contains a real newline inside a quoted span. Without this test, an implementation that synthesized a multiline value by joining unmatched-quote spans across lines could pass T-ENV-12 while violating SPEC 8.1's "no multiline value support" clause. *(Spec 8.1)*
 
 #### Local Env Override (`-e`)
 
@@ -1020,12 +1619,47 @@ All env file parsing tests below use `writeEnvFileRaw` to write exact file conte
 - **T-ENV-21b**: `LOOPX_WORKFLOW` always set, overrides user-supplied value. Script writes `$LOOPX_WORKFLOW` to a marker file. Set `LOOPX_WORKFLOW=fake` in global env. Assert marker contains the real workflow name. *(Spec 8.3)*
 - **T-ENV-21c**: `LOOPX_WORKFLOW` overrides local env file (`-e`) value. Create a local env file containing `LOOPX_WORKFLOW=fake`. Run with `-e <envfile>`. Script writes `$LOOPX_WORKFLOW` to a marker file. Assert marker contains the real workflow name, not `"fake"`. This explicitly tests the highest-precedence layer (loopx-injected) against the second-highest layer (local `-e`). *(Spec 8.3)*
 - **T-ENV-21d**: `LOOPX_PROJECT_ROOT` overrides local env file (`-e`) value. Create a local env file containing `LOOPX_PROJECT_ROOT=/tmp/fake-project-root`. Run with `-e <envfile>`. Script writes `$LOOPX_PROJECT_ROOT` to a marker file. Assert marker contains the real project root (the invocation cwd), not `/tmp/fake-project-root`. This explicitly tests the highest-precedence layer (loopx-injected) against the second-highest layer (local `-e`) for `LOOPX_PROJECT_ROOT`, completing the SPEC 8.3 precedence coverage pattern alongside T-ENV-20b (`LOOPX_BIN`) and T-ENV-21c (`LOOPX_WORKFLOW`). *(Spec 8.3)*
+- **T-ENV-21e**: `LOOPX_BIN` overrides global env-file value. Set up a global env file (via `withGlobalEnv`) containing `LOOPX_BIN=/tmp/fake-binary`. Script observes `LOOPX_BIN` via `observe-env`. Assert the marker records the real injected binary path (a valid executable path that is not `/tmp/fake-binary`). T-ENV-20b covers the local `-e` tier for `LOOPX_BIN`; this test closes the global-env-file tier gap, bringing `LOOPX_BIN` precedence coverage up to the same three-tier pattern as `LOOPX_WORKFLOW` (T-ENV-21b / T-ENV-21c / T-ENV-21e-equivalent). *(Spec 8.1, 8.3)*
+- **T-ENV-21f**: `LOOPX_PROJECT_ROOT` overrides global env-file value. Set up a global env file containing `LOOPX_PROJECT_ROOT=/tmp/fake-project-root`. Script observes `LOOPX_PROJECT_ROOT` via `observe-env`. Assert the marker contains the real project root (the invocation cwd), not `/tmp/fake-project-root`. T-ENV-21a covers the inherited-env tier, T-ENV-21d covers the local `-e` tier; this test closes the global-env-file tier gap for `LOOPX_PROJECT_ROOT`. *(Spec 8.1, 8.3)*
+- **T-ENV-21g**: `LOOPX_WORKFLOW_DIR` overrides global env-file value. Set up a global env file containing `LOOPX_WORKFLOW_DIR=/tmp/fake-dir`. Script observes `LOOPX_WORKFLOW_DIR` via `observe-env`. Assert the marker contains the real injected workflow directory path, not `/tmp/fake-dir`. T-WFDIR-06 covers the inherited-env tier, T-WFDIR-07 covers the local `-e` tier, T-WFDIR-08 covers the `RunOptions.env` tier; this test closes the global-env-file tier gap for `LOOPX_WORKFLOW_DIR`. *(Spec 8.1, 8.3, 6.1)*
+- **T-ENV-21h**: `LOOPX_TMPDIR` overrides global env-file value. Set up a global env file containing `LOOPX_TMPDIR=/tmp/fake-loopx-tmp`. The fixture script observes `LOOPX_TMPDIR` via `observe-env` **and** performs an in-script `stat` of the observed `$LOOPX_TMPDIR` path **during execution** (before the script exits), recording the stat result (exists, is-a-directory) to a marker. The during-run stat is essential because SPEC 7.4 cleanup removes the tmpdir on run completion; a post-run stat would observe absence. Assert: (a) the observed marker records the real injected tmpdir path (under `os.tmpdir()` or the test-isolated parent, matching the `loopx-*` naming pattern), **not** `/tmp/fake-loopx-tmp`, (b) the during-run stat marker records "exists as a directory" — proving it is the real loopx-created tmpdir, not merely a substitution. T-TMP-30 covers the inherited-env tier and T-TMP-31 covers the local `-e` tier; this test closes the global-env-file tier gap for `LOOPX_TMPDIR`, bringing the precedence-coverage pattern for `LOOPX_TMPDIR` in line with `LOOPX_WORKFLOW_DIR`'s full four-tier coverage. *(Spec 8.1, 8.3, 7.4)*
 - **T-ENV-22**: System env has `SYS_VAR=sys`, global env has `SYS_VAR=global`. Script sees `global`. *(Spec 8.3)*
 - **T-ENV-23**: System env has `SYS_VAR=sys`, no loopx override. Script sees `sys`. *(Spec 8.3)*
 - **T-ENV-24**: Full precedence chain. Assert local wins over global over system. *(Spec 8.3)*
 - **T-ENV-24a**: `LOOPX_DELEGATED` is visible in script execution environments when inherited. Spawn loopx with `LOOPX_DELEGATED=1` in the inherited process environment. Script uses `observe-env` fixture for `LOOPX_DELEGATED`. Assert marker contains `{ "present": true, "value": "1" }`. The spec does not require loopx to scrub this variable before spawning scripts — it is part of the inherited system environment. *(Spec 8.3, 3.2)*
+- **T-ENV-24a2**: `LOOPX_DELEGATED` from the **global** env file reaches spawned scripts. Per SPEC 9.5 / 13, `LOOPX_DELEGATED` is startup-reserved only — **not** script-protocol-protected at tier 1. Env files may supply it to spawned scripts. Set up a global env file (via `withGlobalEnv`) containing `LOOPX_DELEGATED=from-global`. Do **not** set `LOOPX_DELEGATED` in loopx's inherited environment. Script observes `LOOPX_DELEGATED` via `observe-env`. Assert marker records `{ "present": true, "value": "from-global" }`. T-ENV-24a covers the inherited-env tier and T-API-58a covers `RunOptions.env`; this test closes the global-env-file gap so all three supply tiers are covered. *(Spec 8.3, 3.2, 9.5, 13)*
+- **T-ENV-24a3**: `LOOPX_DELEGATED` from the **local** env file (`-e`) reaches spawned scripts. Same structure as T-ENV-24a2 but via a local env file: create a local env file containing `LOOPX_DELEGATED=from-local`. Run `loopx run -e <envfile> -n 1 ralph`. Script observes `LOOPX_DELEGATED`. Assert marker records `{ "present": true, "value": "from-local" }`. Completes local-env-file parity alongside T-ENV-24a (inherited), T-ENV-24a2 (global env file), and T-API-58a (`RunOptions.env`). *(Spec 8.3, 3.2, 9.5, 13)*
+- **T-ENV-24a4**: `LOOPX_DELEGATED` is **absent** in spawned scripts when no env tier supplies it — pinning down the SPEC 13 "startup-reserved only ... not injected on every script spawn" guarantee. T-ENV-24a / T-ENV-24a2 / T-ENV-24a3 / T-API-58a all cover the cases where `LOOPX_DELEGATED` is supplied via inherited environment, global env file, local env file, or `RunOptions.env` and reaches the spawned script. T-DEL-07 / T-DEL-07a cover the post-delegation positive case where the delegated loopx process inherits `LOOPX_DELEGATED=1` and that value flows through to scripts. The remaining gap is the **default / non-delegated** case: a non-delegated `loopx run` invocation where `LOOPX_DELEGATED` is **not** present in inherited `process.env`, **not** present in any env file, and **not** supplied by `RunOptions.env` (either programmatically absent or absent because the run is via the CLI). SPEC 13 explicitly lists `LOOPX_DELEGATED` as **startup-reserved only** — distinct from the script-protocol-protected `LOOPX_*` names that loopx must inject on every script spawn — so a conformant implementation must **not** synthesize `LOOPX_DELEGATED` for the script's environment when no tier supplied it. Set up: a clean project with `.loopx/ralph/index.sh` that uses the `observe-env` fixture for `LOOPX_DELEGATED` and emits `stop:true`; **no** project-root `package.json` declaring `loopx` (so project-root delegation does not fire — this is a non-delegated `loopx run`); inherited `process.env` scrubbed of `LOOPX_DELEGATED` (the test harness deletes it from the spawn env before invoking loopx); no global env file containing `LOOPX_DELEGATED` (e.g., `withGlobalEnv` either omits the file or sets a file that does not declare `LOOPX_DELEGATED`); no local `-e` file containing `LOOPX_DELEGATED`. Run `loopx run -n 1 ralph` via the CLI. Assert: (a) exit code 0, (b) the `observe-env` marker for `LOOPX_DELEGATED` records `{ "present": false }` — the variable is not visible in the spawned script's environment, proving loopx did not synthesize it on the per-spawn merge. A buggy implementation that always set `LOOPX_DELEGATED` on every script spawn (e.g., as a sibling of the script-protocol-protected names) would fail assertion (b). This is the explicit default-absence pin for SPEC 13's startup-reserved-only classification. *(Spec 8.3, 3.2, 9.5, 13)*
+- **T-ENV-24a5**: `LOOPX_DELEGATED` is absent in spawned scripts under the **programmatic API** when no env tier supplies it — programmatic-API counterpart to T-ENV-24a4. Same structural setup as T-ENV-24a4 but invoked via `runPromise("ralph", { maxIterations: 1, env: scrubbedEnv })` where `scrubbedEnv` is built explicitly without a `LOOPX_DELEGATED` key (or `runPromise("ralph", { maxIterations: 1 })` with the harness ensuring inherited `process.env` is scrubbed of `LOOPX_DELEGATED` at the loopx-process level). Use the `observe-env` fixture in `.loopx/ralph/index.sh`. Assert: (a) `runPromise` resolves successfully with the script's `Output`, and (b) the `observe-env` marker for `LOOPX_DELEGATED` records `{ "present": false }` — the programmatic-API spawn surface does not synthesize `LOOPX_DELEGATED` either. T-API-58a covers the supplied-via-`RunOptions.env` case; this test pins the absent-by-default case symmetrically. Together with T-ENV-24a4 (CLI surface), this closes the default-absence gap on both run surfaces and locks down SPEC 13's "not injected on every script spawn" rule across the CLI and `runPromise`/`run` programmatic paths. *(Spec 9.5, 8.3, 13)*
+- **T-ENV-24a6**: `LOOPX_DELEGATED` follows **ordinary four-tier precedence** end-to-end — proves it is treated as a non-protocol variable that observes the SPEC 8.3 precedence chain across the four non-protocol tiers (`RunOptions.env` → local env file → global env file → inherited environment, highest precedence first), not the SPEC 8.3 tier-1 protocol-injection override. T-ENV-24a / T-ENV-24a2 / T-ENV-24a3 / T-API-58a each cover a single supply tier in isolation, and T-ENV-24a4 / T-ENV-24a5 cover the absent-by-default case; the SPEC 13 startup-reserved-only classification is also pinned down across those tests. What is **not** explicitly pinned is the **multi-tier precedence chain**: when *all four* non-protocol tiers each supply a different `LOOPX_DELEGATED` value, only the highest-precedence value reaches the spawned script — proving the precedence chain treats `LOOPX_DELEGATED` like any ordinary variable and does **not** route it through a protocol-protected tier-1 override (which would force the loopx-internal recursion-guard value rather than the caller-supplied value). T-ENV-24 already pins down the same four-tier-precedence rule for an arbitrary non-protocol variable (`MYVAR`); this test reproduces the same precedence chain with `LOOPX_DELEGATED` specifically, distinguishing it from the script-protocol-protected `LOOPX_*` names whose own four-tier coverage (T-ENV-21a–21h, T-WFDIR-06–08, T-TMP-30 / T-TMP-31 / T-TMP-21h) instead asserts the **opposite** outcome — that lower tiers are silently overridden by the tier-1 protocol injection. **Setup.** Inject `LOOPX_DELEGATED=from-inherited` into loopx's inherited environment (the test driver's `process.env` before `runPromise` is called, since `runPromise` snapshots inherited env eagerly per SPEC 9.2). Place a global env file via `withGlobalEnv` containing `LOOPX_DELEGATED=from-global`. Place a local env file containing `LOOPX_DELEGATED=from-local`. Set `.loopx/ralph/index.sh` to observe `LOOPX_DELEGATED` via `observe-env` and emit `stop:true`. Drive: `await runPromise("ralph", { envFile: <local-env-file-path>, env: { LOOPX_DELEGATED: "from-options" }, maxIterations: 1 });` Assert: (a) the promise resolves (`LOOPX_DELEGATED` is not a script-protocol-protected name, so the `RunOptions.env` value is not silently overridden), (b) the `observe-env` marker for `LOOPX_DELEGATED` records `{ "present": true, "value": "from-options" }` — `RunOptions.env` (tier 2) wins over local env file (tier 3), global env file (tier 4), and inherited env (tier 5), proving the ordinary precedence chain applied across the non-protocol tiers (the protocol-protected tier 1 is unoccupied because `LOOPX_DELEGATED` is startup-reserved only, not script-protocol-protected). **Important fixture caveat:** `LOOPX_DELEGATED` set in loopx's inherited environment normally **prevents** delegation per SPEC 3.2 / T-DEL-04. This test exercises the case where a non-delegating top-level loopx (because `LOOPX_DELEGATED` is set in inherited env) still merges the four-tier env chain for the spawned script in the normal precedence order; the recursion-guard semantics on the loopx-process side are independent of the spawned-script env-merge. The four-tier test is meaningful precisely because all four non-protocol tiers participate — a buggy implementation that special-cased `LOOPX_DELEGATED` to be sourced from inherited env (tier 5) instead of via the normal merge would produce `"from-inherited"` for the script and fail (b). An implementation that scrubbed `LOOPX_DELEGATED` from the env merge entirely (perhaps to "protect" the recursion guard) would produce an absent observation and also fail (b). Together with the existing per-tier T-ENV-24a / T-ENV-24a2 / T-ENV-24a3 / T-API-58a tests and the absent-default T-ENV-24a4 / T-ENV-24a5 tests, this test pins down `LOOPX_DELEGATED`'s SPEC 13 / 8.3 classification end-to-end: startup-reserved-only on the loopx side, ordinary non-protocol variable on the spawned-script side. *(Spec 8.3, 3.2, 9.5, 13)*
 - **T-ENV-24b**: Empty-string value in local env file overrides non-empty global/system value. *(Spec 8.3)*
 
+#### Env-File Embedded NUL → Spawn Failure
+
+SPEC 7.2 / 9.5 state that runtime rejection of a child environment entry can come from **any env tier** and surfaces as a child launch / spawn failure — "the runtime does not distinguish tiers." The `RunOptions.env` tier is covered (T-API-57 / T-API-57a); these tests close the gap for the local env-file (`-e` / `envFile`) and global env-file tiers.
+
+The spec's env-file parser (SPEC 8.1) rejects keys that do not match `[A-Za-z_][A-Za-z0-9_]*` (so a NUL in a **key** is parser-rejected as a line with an invalid key name, emitting a stderr warning and dropping the line — this path is parser-level, not spawn-level, and already covered by T-ENV-15c for the generic invalid-key case). The spec does not validate NUL in **values** at parse time — values are single-line strings with no escape interpretation, so a literal NUL byte in a value survives parsing. That survived entry reaches the child-spawn step, where the runtime rejects it. Both tests use `writeEnvFileRaw` to write the literal NUL byte into the value.
+
+- **T-ENV-26**: Local env-file (`-e`) with a literal NUL byte in a value surfaces as a spawn failure, not a parser-shape error. Create a local env file at `./.env` via `writeEnvFileRaw(path, "MYVAR=bad\x00val\n")` (a line whose value contains an embedded NUL byte after parsing). Create a valid workflow `.loopx/ralph/index.sh`. Run `loopx run -e .env -n 1 ralph` via the CLI. Assert: (a) exit code 1, (b) stderr contains a child-launch / spawn-failure error referencing the environment-entry rejection (not a parser warning about an invalid key shape), (c) the script did not run (no marker file from `ralph:index`). Per SPEC 7.2, the rejection surfaces as "child launch / spawn failure after tmpdir creation" — `LOOPX_TMPDIR` is created before the spawn step, and its best-effort cleanup runs before the CLI exits with code 1; assert no `loopx-*` dir remains **under the test-isolated `TMPDIR` parent the harness configured for this test, not under the shared `os.tmpdir()` default** (see section 4.7's "Test-parent isolation (flakiness guidance — applies suite-wide)" — every test that inspects for lingering `loopx-*` entries must use an isolated `TMPDIR` parent, including this test). The failure is distinguishable from parser-level failures (e.g., T-ENV-15c, where the line would be dropped with a parser warning and the loop would still attempt to run). *(Spec 7.2, 8.2, 8.3)*
+- **T-ENV-27**: Global env-file with a literal NUL byte in a value surfaces as a spawn failure, not a parser-shape error. Use `withGlobalEnv` to place a global env file containing `MYVAR=bad\x00val` (written via `writeEnvFileRaw` to preserve the literal NUL). Create a valid workflow `.loopx/ralph/index.sh`. Run `loopx run -n 1 ralph` via the CLI (no local `-e`). Assert: (a) exit code 1, (b) stderr contains a child-launch / spawn-failure error (not a parser warning), (c) the script did not run (no marker file), and (d) `LOOPX_TMPDIR` cleanup ran (no lingering `loopx-*` dir **under the test-isolated `TMPDIR` parent — not the shared `os.tmpdir()` default**, per section 4.7's suite-wide isolation guidance). This is the global-env-file tier counterpart to T-ENV-26 (local `-e`) and T-API-57 (`RunOptions.env`), completing the "any env tier can raise a spawn failure" coverage pattern from SPEC 7.2 / 9.5. *(Spec 7.2, 8.1, 8.3)*
+- **T-ENV-26d**: CLI `loopx run -n 3 ralph` — `LOOPX_TMPDIR` is cleaned up after a discovered-script spawn failure caused by **in-loop removal** of the cached script. SPEC 5.1 / 7.2 enumerate "discovered script removed or renamed mid-loop" as one of the spawn-failure triggers that surface as exit `1` after tmpdir creation, and SPEC 7.4 specifies that cleanup runs before exit on every spawn-failure terminal outcome. Existing T-DISC-42a covers the exit-code outcome on the CLI but does **not** assert `LOOPX_TMPDIR` cleanup; T-DISC-42d / T-DISC-42e cover the cleanup contract on the **programmatic** surfaces (`run()` / `runPromise()`). This test pins down the **CLI**-surface cleanup contract for the discovered-script-removed branch — the SPEC 5.1 / 7.2 "removed mid-loop" cleanup trigger on the CLI surface. Set up `.loopx/ralph/index.sh` that, on its first iteration, (a) observes `LOOPX_TMPDIR` into a marker file, (b) `rm`s `.loopx/ralph/check.sh` (the next script in the goto chain), and (c) emits `goto:"check"`. Set up `.loopx/ralph/check.sh` (exists at loop start, gets discovered and cached). Run `loopx run -n 3 ralph` via the CLI **under a test-isolated `TMPDIR` parent** per the section 4.7 suite-wide isolation guidance. Assert: (a) exit code 1 — the second-iteration spawn of `check` fails because the cached path no longer exists on disk, matching T-DISC-42a's exit-code surface, (b) the script's first iteration ran (the `LOOPX_TMPDIR` marker file exists with a recorded path), and (c) **the observed tmpdir path no longer exists on disk** — `LOOPX_TMPDIR` cleanup ran as part of the spawn-failure terminal outcome before the CLI exited. This is the discovered-script-removed counterpart to T-ENV-26 (env-NUL spawn-failure cleanup) on the CLI surface, and the CLI-surface counterpart to T-DISC-42d / T-DISC-42e (programmatic). *(Spec 5.1, 7.2, 7.4)*
+- **T-ENV-26e**: CLI `loopx run -n 3 ralph` — `LOOPX_TMPDIR` is cleaned up after a discovered-script spawn failure caused by **in-loop rename** of the cached script. Rename-variant counterpart to T-ENV-26d for the SPEC 5.1 "discovered script removed or renamed mid-loop" cleanup trigger. Same fixture pattern as T-ENV-26d but the in-loop step is `mv .loopx/ralph/check.sh .loopx/ralph/check-new.sh` instead of `rm`. Set up `.loopx/ralph/index.sh` that, on its first iteration, observes `LOOPX_TMPDIR`, `mv`s `check.sh` to `check-new.sh`, and emits `goto:"check"`. Run `loopx run -n 3 ralph` via the CLI **under a test-isolated `TMPDIR` parent**. Assert: (a) exit code 1 (the cached path for `check` still points to `check.sh`, which no longer exists after the rename — matching T-DISC-42b), (b) the first-iteration `LOOPX_TMPDIR` marker recorded a path, and (c) the observed tmpdir path no longer exists on disk — cleanup ran before exit. Together with T-ENV-26d (removed) and T-DISC-42d / 42e / 42f / 42g (programmatic variants), this closes the SPEC 5.1 / 7.2 / 7.4 "discovered script removed or renamed mid-loop" cleanup-trigger coverage across the CLI and both programmatic surfaces. *(Spec 5.1, 7.2, 7.4)*
+- **T-ENV-26a**: Local env-file (`-e`) with a literal NUL byte in a value under the programmatic API surfaces as a spawn failure **and `LOOPX_TMPDIR` is cleaned up before rejection**. Create a local env file at `./.env` via `writeEnvFileRaw(path, "MYVAR=bad\x00val\n")`. Call `runPromise("ralph", { envFile: ".env", maxIterations: 1 })`. **Run under a test-isolated `TMPDIR` parent** per the section 4.7 suite-wide isolation guidance. Assert: (a) the promise rejects with a spawn-failure error (not an `envFile` shape-validation error — the file exists and is readable, and the parser accepts the value), (b) the script did not run, and (c) **no `loopx-*` directory remains under the test-isolated `TMPDIR` parent** — cleanup ran before the promise rejected. Cleanup is **normative** per SPEC 7.4 "Cleanup triggers" (child launch / spawn failure after tmpdir creation) and SPEC 9.3 "Cleanup ordering is observable. When `LOOPX_TMPDIR` cleanup runs as part of an error path ... it runs before the generator throws or the promise rejects", so the cleanup assertion is required, not optional. This is the programmatic-API counterpart to T-ENV-26. *(Spec 7.2, 7.4, 8.2, 9.3, 9.5)*
+- **T-ENV-27a**: Global env-file with a literal NUL byte in a value under the programmatic API surfaces as a spawn failure **and `LOOPX_TMPDIR` is cleaned up before rejection**. Use `withGlobalEnv` to place a global env file containing `MYVAR=bad\x00val`. Call `runPromise("ralph", { maxIterations: 1 })`. **Run under a test-isolated `TMPDIR` parent** per the section 4.7 suite-wide isolation guidance. Assert: (a) the promise rejects with a spawn-failure error, (b) the script did not run, and (c) **no `loopx-*` directory remains under the test-isolated `TMPDIR` parent** — cleanup ran before the promise rejected. Cleanup is normative per SPEC 7.4 / 9.3, so the cleanup assertion is required, not optional. This is the programmatic-API counterpart to T-ENV-27 and closes global-env-file NUL-in-value coverage on both run surfaces. *(Spec 7.2, 7.4, 8.1, 9.3)*
+- **T-ENV-26f**: Generator-surface counterpart to T-ENV-26a — `run("ralph", { envFile: ".env", maxIterations: 1 })` with a local env file containing a literal NUL byte in a value throws a spawn failure on first `next()` and `LOOPX_TMPDIR` is cleaned up before the throw. SPEC 7.2 / 7.4 / 9.1 / 9.3 specify that the generator surface uses the same pre-iteration error path as `runPromise()` for spawn failures, and SPEC 7.4's cleanup-trigger list ("Child launch / spawn failure after tmpdir creation") is independent of which run surface is in use. T-ENV-26 covers the CLI surface and T-ENV-26a covers `runPromise()`; the existing `RunOptions.env` matrix has `run()` generator counterparts at T-API-57h / T-API-57i for the `RunOptions.env` tier, but the local env-file (`-e` / `envFile`) tier is missing its `run()` counterpart. This test closes that gap. Create a local env file at `./.env` via `writeEnvFileRaw(path, "MYVAR=bad\x00val\n")` (literal NUL in value, parser-accepted). Create `.loopx/ralph/index.sh` (any valid script). **Run under a test-isolated `TMPDIR` parent** per the section 4.7 suite-wide isolation guidance. Drive `const g = run("ralph", { envFile: ".env", maxIterations: 1 }); await g.next();`. Assert: (a) the first `next()` rejects (the generator throws) with a spawn-failure error — not an envFile shape-validation error (the file exists, is readable, and the parser accepts the value), (b) the workflow script did not run (no marker file from `ralph:index`), and (c) **no `loopx-*` directory remains under the test-isolated `TMPDIR` parent** — cleanup ran before the throw, mirroring SPEC 9.3's "Cleanup ordering is observable" clause on the generator surface. Together with T-ENV-26 (CLI), T-ENV-26a (`runPromise()`), and this test (`run()`), the local-env-file NUL-in-value spawn-failure path is pinned across all three run surfaces. *(Spec 7.2, 7.4, 8.2, 9.1, 9.3)*
+- **T-ENV-27d**: Generator-surface counterpart to T-ENV-27a — `run("ralph", { maxIterations: 1 })` with a global env file containing a literal NUL byte in a value throws a spawn failure on first `next()` and `LOOPX_TMPDIR` is cleaned up before the throw. Same SPEC contract as T-ENV-26f applied to the global-env-file tier (SPEC 8.1 instead of 8.2). T-ENV-27 covers CLI and T-ENV-27a covers `runPromise()`; this test closes the `run()` generator gap for the global-env-file tier, completing the three-surface matrix. Use `withGlobalEnv` to place a global env file containing `MYVAR=bad\x00val` (written via `writeEnvFileRaw` to preserve the literal NUL). Create `.loopx/ralph/index.sh`. **Run under a test-isolated `TMPDIR` parent** per the section 4.7 suite-wide isolation guidance. Drive `const g = run("ralph", { maxIterations: 1 }); await g.next();` (no local `-e` / `envFile`). Assert: (a) the first `next()` rejects with a spawn-failure error (not a parser warning — the parser does not validate NUL in values per SPEC 8.1), (b) the workflow script did not run, and (c) **no `loopx-*` directory remains under the test-isolated `TMPDIR` parent** — cleanup ran before the throw. Together with T-ENV-26f (`run()` + local env file), T-ENV-26a / T-ENV-27a (`runPromise()` + local / global env file), T-ENV-26 / T-ENV-27 (CLI + local / global env file), and T-API-57 / T-API-57a / T-API-57h / T-API-57i (`RunOptions.env` tier on both programmatic surfaces), this completes the SPEC 7.2 / 9.5 "the runtime does not distinguish tiers" coverage matrix across all three env-supplying tiers (`RunOptions.env`, local env file, global env file) and all three run surfaces (CLI, `runPromise()`, `run()`). *(Spec 7.2, 7.4, 8.1, 9.1, 9.3)*
+
+###### NUL-in-Value + Zero-Iteration (No Spawn → No Spawn-Failure Surface)
+
+T-ENV-26 / T-ENV-26a / T-ENV-27 / T-ENV-27a above all run with `-n 1` / `maxIterations: 1`, where the spawn step actually executes and the runtime-rejection path surfaces. Under `-n 0` / `maxIterations: 0`, however, SPEC 4.2 / 9.5 / 7.1 specify that no child is spawned — env files are still loaded and parsed (validating readability and parser-level shape, per T-ENV-25b / T-ENV-25c / T-CLI-22f / T-API-08e/08f/08p/08p2), but the runtime's environment-building step never executes, so a NUL byte that would otherwise raise a spawn failure silently survives the (skipped) spawn step. These tests pin down the no-spawn-no-spawn-failure contract on the env-file tier.
+
+- **T-ENV-26b**: CLI `loopx run -e .env -n 0 ralph` with a local env file containing `MYVAR=bad\x00val` exits with code 0 (parses but does not spawn). Create the local env file via `writeEnvFileRaw(path, "MYVAR=bad\x00val\n")` (literal NUL in value, parser-accepted). Create `.loopx/ralph/index.sh` (any valid script). Run `loopx run -e .env -n 0 ralph` via the CLI. Assert: (a) exit code 0 (per SPEC 4.2 `-n 0` exits 0 on success), (b) stderr contains no spawn-failure error and no parser warning about NUL (the parser does not validate NUL in values per SPEC 8.1), (c) the script did not run (no marker file from `ralph:index`), (d) no `LOOPX_TMPDIR` was created (per SPEC 7.4 — tmpdir creation is skipped under `-n 0`; assert against a test-isolated `TMPDIR` parent per the section 4.7 suite-wide isolation guidance). The env-file readability and parser-level validation still ran (else the failure would surface as exit 1 per T-ENV-25b/T-CLI-22f), but the runtime-rejection step did not. This is the zero-iteration counterpart to T-ENV-26 (which surfaces the spawn failure at `-n 1`). *(Spec 4.2, 7.1, 7.4, 8.1, 8.2)*
+- **T-ENV-26c**: Programmatic `runPromise("ralph", { envFile: ".env", maxIterations: 0 })` with a local env file containing `MYVAR=bad\x00val` resolves `[]`. Same env-file setup as T-ENV-26b. Assert: (a) the promise resolves (no rejection), (b) the resolved value is `[]`, (c) no spawn-failure error on stderr, (d) the script did not run, (e) no `LOOPX_TMPDIR` was created. Programmatic-API counterpart to T-ENV-26b. *(Spec 9.2, 9.5, 7.1, 7.4, 8.2)*
+- **T-ENV-27b**: CLI `loopx run -n 0 ralph` with a global env file containing `MYVAR=bad\x00val` exits with code 0. Use `withGlobalEnv` to place the global env file (written via `writeEnvFileRaw` to preserve the NUL). Create `.loopx/ralph/index.sh`. Run `loopx run -n 0 ralph` via the CLI (no local `-e`). Assert: (a) exit code 0, (b) no spawn-failure error on stderr, no parser warning about NUL, (c) the script did not run, (d) no `LOOPX_TMPDIR` was created (assert against test-isolated `TMPDIR` parent). Global-env-file counterpart to T-ENV-26b. *(Spec 4.2, 7.1, 7.4, 8.1)*
+- **T-ENV-27c**: Programmatic `runPromise("ralph", { maxIterations: 0 })` with a global env file containing `MYVAR=bad\x00val` resolves `[]`. Same global-env-file setup as T-ENV-27b. Assert: (a) resolves, (b) value is `[]`, (c) no spawn-failure error on stderr, (d) script did not run, (e) no `LOOPX_TMPDIR` created. Programmatic-API counterpart to T-ENV-27b and closes the four-test matrix (CLI / API × local / global) for "NUL in env value under zero-iteration is silently survived". Together with T-API-57d / T-API-57e / T-API-57f for the `RunOptions.env` tier under zero iteration, this completes the zero-iteration NUL-in-env-tier coverage for SPEC 7.2 / 9.5's "the runtime does not distinguish tiers" clause when applied to the no-spawn case. *(Spec 9.2, 9.5, 7.1, 7.4, 8.1)*
+- **T-ENV-26g**: Generator-surface counterpart to T-ENV-26c — `run("ralph", { envFile: ".env", maxIterations: 0 })` with a local env file containing `MYVAR=bad\x00val` completes immediately on first `next()` with `{ done: true, value: undefined }` and yields no outputs. Same SPEC contract as T-ENV-26c on the `runPromise()` surface, applied to the `run()` generator surface (parallel to T-API-57f / T-API-57f2 for the `RunOptions.env` tier under zero iteration). Under `maxIterations: 0` no spawn occurs, so the NUL value silently survives the (skipped) spawn step on the generator surface as well. Same env-file setup as T-ENV-26b: write the local env file via `writeEnvFileRaw(path, "MYVAR=bad\x00val\n")`. Drive `const g = run("ralph", { envFile: ".env", maxIterations: 0 }); const r = await g.next();`. Assert: (a) `r` is `{ done: true, value: undefined }` (no first yield), (b) no spawn-failure error on stderr, (c) the script did not run (no marker file), (d) no `LOOPX_TMPDIR` was created (assert against a test-isolated `TMPDIR` parent per the section 4.7 suite-wide isolation guidance). *(Spec 9.1, 9.5, 7.1, 7.4, 8.2)*
+- **T-ENV-27e**: Generator-surface counterpart to T-ENV-27c — `run("ralph", { maxIterations: 0 })` with a global env file containing `MYVAR=bad\x00val` completes immediately on first `next()` with `{ done: true, value: undefined }` and yields no outputs. Global-env-file counterpart to T-ENV-26g. Same SPEC contract: under `maxIterations: 0` no spawn occurs, so the NUL value in the global-env tier silently survives the (skipped) spawn step on the generator surface. Same setup as T-ENV-27b: place the global env file via `withGlobalEnv` with `MYVAR=bad\x00val` (written via `writeEnvFileRaw`). Drive `const g = run("ralph", { maxIterations: 0 }); const r = await g.next();`. Assert: (a) `r` is `{ done: true, value: undefined }`, (b) no spawn-failure error on stderr, (c) the script did not run, (d) no `LOOPX_TMPDIR` was created (assert against a test-isolated `TMPDIR` parent). Together with T-ENV-26g, this closes the `run()` generator surface for the zero-iteration NUL-in-env-file matrix and completes the run-surface × env-tier × iteration-count coverage of SPEC 7.2 / 9.5's "runtime does not distinguish tiers" clause for the env-file tiers. *(Spec 9.1, 9.5, 7.1, 7.4, 8.1)*
+
 #### Env Caching
 
 - **T-ENV-25**: During a multi-iteration loop, modify the global env file between iterations. Assert the marker contains the original value. *(Spec 8.1)*
@@ -1033,6 +1667,328 @@ All env file parsing tests below use `writeEnvFileRaw` to write exact file conte
 - **T-ENV-25b**: `loopx run -n 0 ralph` with an unreadable global env file → exits with code 1. Global env loading and validation happens before the `-n 0` short-circuit. **Conditional on `process.getuid() !== 0`.** *(Spec 4.2, 8.1)*
 - **T-ENV-25c**: `loopx run -n 0 ralph` with a malformed-but-readable global env file (e.g., containing `1BAD=val`) → exits with code 0, stderr contains a parser warning for the invalid key. Proves global env files are actually parsed under `-n 0`, not just existence/readability checked. This is the global-env counterpart to T-CLI-22c (which covers the local `-e` file under `-n 0`). *(Spec 4.2, 8.1)*
 
+#### `LOOPX_WORKFLOW_DIR`
+
+Spec 6.1 and 8.3 make `LOOPX_WORKFLOW_DIR` a script-protocol-protected variable derived from the cached discovery-time path of the currently-spawned script. These tests pin down its lifecycle and precedence semantics.
+
+- **T-WFDIR-01**: `LOOPX_WORKFLOW_DIR` is injected into every script spawn, and its spelling is byte-for-byte equal to the authoritative discovery-time workflow-directory path. `.loopx/ralph/index.sh` uses `observe-env` on `LOOPX_WORKFLOW_DIR` to record the injected value into a marker file, and in the same script writes `"$(dirname "$0")"` to a second marker via `write-value-to-file` (`printf '%s'`, exact-byte safe). Assert: (a) the `LOOPX_WORKFLOW_DIR` marker records `{ "present": true, "value": <spelling> }` where `<spelling>` is an absolute path equal to the expected discovery-time workflow directory path, (b) `<spelling>` is byte-identical to the `dirname "$0"` marker's content (SPEC 6.2 normatively states that Bash `dirname "$0"` equals `LOOPX_WORKFLOW_DIR` byte-for-byte), and (c) exit 0. Trailing-slash variation between the two markers is **not** permitted — the test asserts a single authoritative spelling, not an equivalence class that allows trailing-slash drift, because SPEC 6.2's byte-for-byte guarantee forecloses that drift. *(Spec 6.1, 6.2, 8.3)*
+- **T-WFDIR-02**: `LOOPX_WORKFLOW_DIR` equals the discovered workflow directory path. Set up `.loopx/ralph/index.sh`. Observe `LOOPX_WORKFLOW_DIR` and also record the project root via `LOOPX_PROJECT_ROOT`. Assert that `LOOPX_WORKFLOW_DIR === path.join(LOOPX_PROJECT_ROOT, ".loopx", "ralph")` in the v1 layout. The injected form is derived from the cached discovery path, not recomposed. *(Spec 6.1)*
+- **T-WFDIR-03**: `LOOPX_WORKFLOW_DIR` is refreshed per-spawn on intra-workflow goto. `ralph:index` outputs `goto:"check"`, and `ralph:check` observes `LOOPX_WORKFLOW_DIR`. Both `ralph:index` and `ralph:check` record markers (distinct files keyed by script name). Assert: both markers record `<abs>/.loopx/ralph` — intra-workflow goto preserves the workflow dir. *(Spec 6.1, 8.3)*
+- **T-WFDIR-04**: `LOOPX_WORKFLOW_DIR` changes on cross-workflow goto. `ralph:index` outputs `goto:"other:check"`; `other:check` observes `LOOPX_WORKFLOW_DIR` into a distinct marker file. Also observe `LOOPX_WORKFLOW` to cross-check. Assert: `ralph:index`'s marker has value `<abs>/.loopx/ralph` and `other:check`'s marker has value `<abs>/.loopx/other` — `LOOPX_WORKFLOW_DIR` is refreshed before the B-side spawn. Additionally, cwd remains the project root across the transition (T-EXEC-16b) — `LOOPX_WORKFLOW_DIR` is the per-spawn workflow-relative surface, cwd is not. *(Spec 6.1, 8.3)*
+- **T-WFDIR-04a**: Deeper cross-workflow chain (A → B → C) observes each workflow's own directory. Three workflows, each with a script that observes `LOOPX_WORKFLOW_DIR` into its own marker file before emitting goto to the next. Assert the three markers contain `.loopx/alpha`, `.loopx/beta`, `.loopx/gamma` respectively. *(Spec 6.1)*
+- **T-WFDIR-05**: `LOOPX_WORKFLOW_DIR` resets correctly when the loop returns to the starting target. `alpha:index` outputs `goto:"beta:step"`. `beta:step` outputs no goto (loop resets). Both scripts observe `LOOPX_WORKFLOW_DIR` appending to a markers log keyed by iteration. Run with `-n 3`. Assert: alpha's log shows `.loopx/alpha` on both its first and third iterations, and beta's log shows `.loopx/beta` on the second iteration — the reset iteration sees `LOOPX_WORKFLOW_DIR` set back to the starting workflow's directory. *(Spec 6.1, 2.2)*
+- **T-WFDIR-06**: `LOOPX_WORKFLOW_DIR` overrides inherited system-env values of the same name. Spawn loopx with `LOOPX_WORKFLOW_DIR=/tmp/fake-dir` in the inherited process environment. Script observes `LOOPX_WORKFLOW_DIR`. Assert the marker contains the real injected workflow directory path, not `/tmp/fake-dir`. Protocol variables win at tier 1 (Spec 8.3). *(Spec 8.3)*
+- **T-WFDIR-07**: `LOOPX_WORKFLOW_DIR` overrides local env file (`-e`) value. Create a local env file containing `LOOPX_WORKFLOW_DIR=/tmp/fake-dir`. Run with `-e <envfile>`. Script observes `LOOPX_WORKFLOW_DIR`. Assert the marker contains the real injected path, not `/tmp/fake-dir`. This explicitly tests the highest-precedence layer (loopx-injected) against the second-highest layer (local `-e`) for `LOOPX_WORKFLOW_DIR`, completing the Spec 8.3 precedence coverage pattern established by T-ENV-20b / T-ENV-21c / T-ENV-21d. *(Spec 8.3)*
+- **T-WFDIR-08**: `LOOPX_WORKFLOW_DIR` overrides `RunOptions.env` value. Call `run("ralph", { env: { LOOPX_WORKFLOW_DIR: "/tmp/fake-dir" } })`. Script observes `LOOPX_WORKFLOW_DIR`. Assert the marker contains the real injected path, not `/tmp/fake-dir`. Per Spec 8.3, protocol-variable injection is tier 1 and `RunOptions.env` is tier 2 — `RunOptions.env` entries for `LOOPX_*` keys are silently overridden. *(Spec 8.3, 9.5)*
+- **T-WFDIR-09**: Bash execution path — `$(dirname "$0") == LOOPX_WORKFLOW_DIR` byte-for-byte, regardless of symlinks. `.loopx/ralph/index.sh` performs: `write-value-to-file "$LOOPX_WORKFLOW_DIR" <wfdirMarkerPath>` and `write-value-to-file "$(dirname "$0")" <dirnameMarkerPath>`. Both markers are written via the `write-value-to-file` fixture (`printf '%s'`, exact-byte safe, no trailing newline). Assert the two marker files' byte contents are equal. This is a normative Bash invariant per Spec 6.1 "Invocation path" / 6.2 — loopx invokes Bash with the absolute discovery-time path, and Bash does not canonicalize `$0`. *(Spec 6.1, 6.2)*
+- **T-WFDIR-09a**: Bash `$0` equals the **absolute discovery-time path of the entry script** byte-for-byte — non-symlinked case. SPEC 6.2 normatively says "Bash `$0` is the absolute discovery-time path of the entry script." T-WFDIR-09 pins down the `dirname "$0"` relation against `LOOPX_WORKFLOW_DIR` (which itself is derived from the script path's directory portion), but does not pin down that `$0` equals the full absolute script path. Create `.loopx/ralph/index.sh` that writes `"$0"` via `write-value-to-file` to a marker, `"$LOOPX_WORKFLOW_DIR/index.sh"` (the expected cached absolute path, composed from the authoritative workflow-dir spelling plus the entry script basename `index.sh`) to a second marker, and then emits `stop:true`. Assert the two marker files are byte-identical. Normal non-symlinked case — `$0` is the absolute discovery-time path and matches the expected cached spelling. *(Spec 6.1, 6.2)*
+- **T-WFDIR-09b**: Bash `$0` under a symlinked workflow directory preserves the symlink spelling byte-for-byte. Set up `/tmp/real-workflows/ralph/index.sh` (real workflow directory outside `.loopx/`) and symlink `<project>/.loopx/ralph -> /tmp/real-workflows/ralph`. `index.sh` writes `"$0"` to a marker via `write-value-to-file`. Run `loopx run -n 1 ralph` from `<project>/`. Assert the marker contains `<project>/.loopx/ralph/index.sh` (symlink-preserving discovery-time spelling) and **not** `/tmp/real-workflows/ralph/index.sh` (realpath-canonicalized spelling) — per Spec 6.2, Bash does not canonicalize `$0`, and per Spec 5.1's symlink policy the cached discovery-time spelling is preserved. This is the symlinked-workflow-directory counterpart to T-WFDIR-09a. *(Spec 6.1, 6.2, 5.1)*
+- **T-WFDIR-09c**: Bash `$0` under a symlinked entry script preserves the symlink spelling byte-for-byte. Set up `/tmp/real-script.sh` (real entry script outside `.loopx/`) and symlink `<project>/.loopx/ralph/index.sh -> /tmp/real-script.sh`. The real script writes `"$0"` to a marker via `write-value-to-file`. Run `loopx run -n 1 ralph`. Assert the marker contains `<project>/.loopx/ralph/index.sh` (symlink-preserving spelling) and **not** `/tmp/real-script.sh` (realpath-canonicalized spelling). Counterpart to T-WFDIR-09b on the entry-script-symlink axis. Together with T-WFDIR-09b (symlinked workflow directory) this closes the symlink-spelling coverage for Bash `$0` across both symlink axes normatively enumerated in Spec 6.2. *(Spec 6.1, 6.2, 5.1)*
+- **T-WFDIR-09d**: Bash `$0` under a symlinked **`.loopx` directory** preserves the symlink spelling byte-for-byte. SPEC 6.2 says Bash `$0` is the absolute discovery-time path of the entry script, and SPEC 5.1 / 6.1 specify that the discovery-time spelling preserves symlinks at any intermediate component — including `.loopx` itself. T-WFDIR-09b covers a symlinked workflow directory (`<project>/.loopx/ralph -> /tmp/real-workflows/ralph`) and T-WFDIR-09c covers a symlinked entry script; T-WFDIR-11 covers a symlinked `.loopx` for `LOOPX_WORKFLOW_DIR` but not for Bash `$0`. This test closes the `.loopx`-symlink axis for `$0`. Set up real workflows at `/tmp/real-loopx/ralph/index.sh` (real workflow tree outside the project) and symlink `<project>/.loopx -> /tmp/real-loopx`. The real `index.sh` writes `"$0"` to a marker via `write-value-to-file` and `"$LOOPX_WORKFLOW_DIR"` to a second marker via `observe-env`. Run `loopx run -n 1 ralph` from `<project>/`. Assert: (a) the `$0` marker contains `<project>/.loopx/ralph/index.sh` (symlink-preserving discovery-time spelling, with `.loopx` itself a symlink) and **not** `/tmp/real-loopx/ralph/index.sh` (realpath-canonicalized spelling), per Spec 6.2 "Bash does not canonicalize `$0`" and Spec 5.1's symlink preservation policy applied to the `.loopx` parent component, and (b) `$(dirname "$0") == LOOPX_WORKFLOW_DIR` — i.e., the second marker (`LOOPX_WORKFLOW_DIR`) equals the directory portion of the first marker (`$0`) byte-for-byte. This (b) clause carries the T-WFDIR-09 normative-Bash-equality contract through the `.loopx`-symlink case, ensuring the two values stay in lockstep when the symlink lives at the `.loopx` component rather than at the workflow-dir or entry-script component. Together with T-WFDIR-09b (symlinked workflow dir) and T-WFDIR-09c (symlinked entry script), this closes the three symlink-axis cases for Bash `$0`. *(Spec 6.1, 6.2, 5.1)*
+- **T-WFDIR-10**: Symlinked workflow directory — discovery-time spelling is preserved. Create a real workflow directory at `/tmp/real-workflows/ralph/` (containing `index.sh` that observes `LOOPX_WORKFLOW_DIR`). Symlink `<project>/.loopx/ralph → /tmp/real-workflows/ralph`. Run `loopx run ralph`. Assert the marker value includes the symlinked spelling (`<project>/.loopx/ralph`), **not** the realpath (`/tmp/real-workflows/ralph`). Per Spec 6.1, `LOOPX_WORKFLOW_DIR` is derived from the discovery-time path and does not apply `realpath`. *(Spec 6.1)*
+- **T-WFDIR-11**: Symlinked `.loopx` directory — discovery-time spelling is preserved. Create real workflows at `/tmp/real-loopx/ralph/index.sh`. Symlink `<project>/.loopx → /tmp/real-loopx`. Run `loopx run ralph`. Assert `LOOPX_WORKFLOW_DIR` uses the symlinked spelling (`<project>/.loopx/ralph`), not `/tmp/real-loopx/ralph`. *(Spec 6.1)*
+- **T-WFDIR-12**: Symlinked entry script file — discovery-time spelling is preserved. Create a real script at `/tmp/real-script.sh`. Symlink `<project>/.loopx/ralph/index.sh → /tmp/real-script.sh`. Run `loopx run ralph`. Assert `LOOPX_WORKFLOW_DIR` is the symlinked workflow directory (`<project>/.loopx/ralph`), independent of the entry-script symlink target. Additionally (from T-WFDIR-09's normative Bash equality), `$(dirname "$0")` must equal `LOOPX_WORKFLOW_DIR`. *(Spec 6.1)*
+- **T-WFDIR-13**: Top-level script and a sourced helper both observe the same `LOOPX_WORKFLOW_DIR`. `.loopx/ralph/index.sh` sources `.loopx/ralph/lib/helper.sh`. Both the top-level script and the helper (sourced into the same process) write `LOOPX_WORKFLOW_DIR` to separate marker files. Assert both markers contain identical values. Env vars are injected once per child spawn and inherited by the whole process. *(Spec 6.1)*
+- **T-WFDIR-13a**: Top-level JS/TS script and an imported helper module both observe the same `LOOPX_WORKFLOW_DIR`. `.loopx/ralph/index.ts` imports `./lib/helper.ts`; both write `process.env.LOOPX_WORKFLOW_DIR` to separate marker files before `output({ stop: true })`. Assert both markers contain identical values. This is the JS/TS import counterpart to T-WFDIR-13's sourced-shell-helper case. *(Spec 6.1)*
+- **T-WFDIR-14**: `LOOPX_WORKFLOW_DIR` is a cross-workflow rendezvous anti-pattern sanity check. `alpha:index` writes a file `<LOOPX_WORKFLOW_DIR>/shared.tmp` then gotos `beta:index`. `beta:index` reads from its **own** `LOOPX_WORKFLOW_DIR/shared.tmp`. Assert `beta:index` reports file-not-found — `LOOPX_WORKFLOW_DIR` always points at the currently-spawned script's own workflow and is not a rendezvous point. Documents Spec 6.1's "Cross-workflow rendezvous" clarification that `$LOOPX_TMPDIR` (or a shared fixed location) is the correct rendezvous surface. *(Spec 6.1)*
+
+#### `LOOPX_TMPDIR` (Run-Scoped Temporary Directory)
+
+Spec 7.4 describes `LOOPX_TMPDIR` lifecycle, cleanup, and snapshot semantics. This block is a full coverage pass. All tests use `observe-env` to capture `LOOPX_TMPDIR` into marker files, plus direct filesystem inspection where needed (identity checks, mode, file persistence).
+
+**Test-parent isolation (flakiness guidance — applies suite-wide, not just to this block).** **Every test that inspects `os.tmpdir()` (or any shared default tmpdir parent) for `loopx-*` entries — presence or absence, before/after snapshots, negative-observation assertions, lingering-entry assertions after a spawn-failure cleanup, etc. — must run under an isolated tmpdir parent rather than scanning the shared `os.tmpdir()` default (typically `/tmp`).** Use a per-test parent such as `await fs.mkdtemp(path.join(os.tmpdir(), "loopx-test-parent-"))` and set `TMPDIR` on loopx's inherited environment to that per-test parent for the duration of the test, then clean the parent at test teardown. This applies to (non-exhaustive list):
+
+- Negative "no `loopx-*` dir was created" assertions in this block (T-TMP-10, T-TMP-11, T-TMP-12, T-TMP-12a/b/c, T-API-68e, T-API-69c, and any similar carve-out tests).
+- Before/after snapshots of the tmpdir parent (T-TMP-32).
+- Tests that assert the tmpdir path lives under a specific parent — rebase the assertion against the isolated parent rather than the global `os.tmpdir()` default.
+- **Tests outside this block that assert `LOOPX_TMPDIR` cleanup ran by checking for the absence of lingering `loopx-*` entries under `os.tmpdir()`.** Specifically: env-file embedded NUL spawn-failure tests (T-ENV-26, T-ENV-26a, T-ENV-27, T-ENV-27a) which assert the spawn-failure path's best-effort tmpdir cleanup; programmatic-API spawn-failure rejection tests with similar lingering-entry assertions (e.g., T-API-57 / T-API-57a for `RunOptions.env` NUL); and any future test that pattern-matches against `loopx-*` entries under `os.tmpdir()` for either positive (presence) or negative (absence / cleanup-completed) outcomes. These tests must each set an isolated `TMPDIR` parent, restrict the `loopx-*` scan to that isolated parent (not `/tmp` globally), and clean it at teardown.
+
+This avoids two flakiness modes: (a) concurrent test workers racing to create `loopx-*` entries under the shared `/tmp` parent, making negative assertions fail nondeterministically; (b) leftover `loopx-*` entries from prior runs being miscounted. Tests that assert cleanup (T-TMP-13 and later) can also observe the isolated parent to assert "no lingering entries under this test's parent" as a stronger, scope-bounded variant of the global scan.
+
+**Warning-text broadness.** Cleanup-warning and tmpdir-warning assertions across this block follow the same "implementation-defined text" convention: assert **cardinality** (at most one cleanup warning per run per SPEC 7.4) and **side-effect outcomes** (exit code, filesystem state), but do **not** assert specific phrasing, path mentions, or type mentions. T-TMP-35/T-TMP-36 are the canonical examples; other warning assertions throughout this block (creation-failure warnings, cleanup-failure warnings, etc.) follow the same convention.
+
+**Cleanup-warning detection (harness rule).** Cleanup-warning cardinality assertions across this block (and their parametrized counterparts under signal / abort / script-error terminals — T-TMP-35*, T-TMP-36*, T-TMP-38*, T-TMP-40, T-TMP-41, T-TMP-42, T-TMP-42a, T-TMP-42b, T-TMP-42c, T-TERM-03, T-INST-116l, etc.) use the **section 1.4 cleanup-warning structured marker seam** (the `LOOPX_TEST_CLEANUP_WARNING\t…` stderr line declared there) as their implementation-neutral detection predicate. The harness counts only lines beginning with `LOOPX_TEST_CLEANUP_WARNING\t` as cleanup-warning emissions; the human-readable warning text alongside the marker is not part of the cardinality count, and the negative form ("no cleanup-related warning" — used by T-TMP-12a and similar zero-warning paths) inverts the predicate. See section 1.4 for the seam's full contract, gating, discovery, and disambiguation guarantees.
+
+##### Creation and Scope
+
+- **T-TMP-01**: `LOOPX_TMPDIR` is created once per run and injected into every script spawn. Run a two-iteration loop where both iterations observe `LOOPX_TMPDIR` **and** each script performs its own `stat` of `$LOOPX_TMPDIR` **during** its own execution, recording the stat result (exists, is-a-directory) to a per-iteration marker before the script exits. The during-run stat is essential: after the final iteration the run completes and SPEC 7.4 cleanup removes the directory, so a post-run stat would observe absence. Assert: (a) both markers contain the same absolute path, (b) both per-iteration during-run stat markers record "exists as a directory", (c) the observed path is parented under `os.tmpdir()` (or the test-isolated tmpdir parent — see section 4.7 tmpdir test quality note), and (d) after loopx exits, the path has been cleaned up (post-run stat returns ENOENT). *(Spec 7.4, 8.3)*
+- **T-TMP-02**: `LOOPX_TMPDIR` is an absolute path. Observe `LOOPX_TMPDIR` in a script. Assert the marker value starts with `/` (POSIX) and equals its own `path.resolve()`. *(Spec 7.4)*
+- **T-TMP-02a**: `LOOPX_TMPDIR` basename starts with the `loopx-` prefix. SPEC 7.4 normatively says "The directory is created under the selected parent via `mkdtemp` with a `loopx-` prefix" — the `loopx-` prefix is the explicit naming contract. Existing tests scan for `loopx-*` entries under the test-isolated tmpdir parent (e.g., T-TMP-10 / T-TMP-11 / T-TMP-12 / T-TMP-32) but they observe the prefix indirectly via glob-pattern enumeration of the parent directory, not as a direct assertion on the `LOOPX_TMPDIR` value itself. A direct positive assertion clarifies the contract and catches an implementation that picked a different prefix (`tmp-loopx-…`, `loopx_…`, `lx-…`, etc.) — such an implementation would still satisfy "absolute path" / "under `os.tmpdir()`" / "removed after cleanup" but would silently violate the prefix contract that the rest of the test suite relies on for entry enumeration. Set up `.loopx/ralph/index.sh` that observes `LOOPX_TMPDIR` via `observe-env` into a marker, then emits `stop:true`. Run `loopx run -n 1 ralph` (CLI). After loopx exits 0, read the observed `LOOPX_TMPDIR` value from the marker and assert: (a) `path.basename(observedTmpdir).startsWith("loopx-")` — the basename has the explicit `loopx-` prefix, not just a coincidental substring match anywhere in the path, and (b) the basename has at least one additional character after `loopx-` (the `mkdtemp` random suffix — `mkdtemp("loopx-")` always produces a basename longer than the prefix itself). T-TMP-02 covers absoluteness; this test covers the prefix shape directly. *(Spec 7.4)*
+- **T-TMP-03**: `LOOPX_TMPDIR` shared across iterations. `.loopx/ralph/index.sh` observes `LOOPX_TMPDIR` on each iteration and appends to a log. Run with `-n 3`. Assert all three entries are identical — the tmpdir is stable for the lifetime of the run. *(Spec 7.4)*
+- **T-TMP-04**: `LOOPX_TMPDIR` shared across intra-workflow goto. `ralph:index` outputs `goto:"check"`; `ralph:check` outputs `stop:true`. Both observe `LOOPX_TMPDIR` into separate markers. Assert identical values. *(Spec 7.4)*
+- **T-TMP-05**: `LOOPX_TMPDIR` shared across cross-workflow goto. `alpha:index` outputs `goto:"beta:step"`; `beta:step` outputs `stop:true`. Both observe `LOOPX_TMPDIR`. Assert identical values — cross-workflow transitions do not refresh the tmpdir. *(Spec 7.4)*
+- **T-TMP-06**: `LOOPX_TMPDIR` preserved across loop reset. `alpha:index` outputs `goto:"beta:step"`; `beta:step` outputs no goto (loop resets to `alpha:index`). Both observe `LOOPX_TMPDIR` on each iteration. Run with `-n 3`. Assert all three observations are identical. *(Spec 7.4)*
+- **T-TMP-07**: Files written to `LOOPX_TMPDIR` persist within a run. `ralph:index` writes `"hello"` to `$LOOPX_TMPDIR/state.txt` then gotos `ralph:check`. `ralph:check` reads `$LOOPX_TMPDIR/state.txt` and outputs it as `result`. Observe via `runPromise`. Assert the second yielded output's `result` is `"hello"`. *(Spec 7.4)*
+- **T-TMP-08**: Concurrent runs get distinct tmpdirs — across **independent projects**. Launch two `runPromise` invocations in parallel (or two CLI runs) against two independent projects. Each records its `LOOPX_TMPDIR` via `observe-env`. Assert the two recorded paths differ. *(Spec 7.4)*
+- **T-TMP-08a**: Concurrent **`runPromise()`** invocations against the **same project** also get distinct tmpdirs. SPEC 7.4 "Concurrent runs are isolated. Each run receives its own distinct directory" is keyed on the run, not on the project — two parallel runs that share a `.loopx/` and project root must still receive separate tmpdirs. T-TMP-08 covers the independent-projects case but would not catch an implementation that incorrectly keyed tmpdir creation on project root (one tmpdir per project, reused across concurrent runs against the same project). Set up a single project with `.loopx/ralph/index.sh` that observes `LOOPX_TMPDIR` into a marker file and emits `stop:true`. **The marker file path must be external to `LOOPX_TMPDIR` itself**, because SPEC 7.4 requires tmpdir cleanup on normal completion — any marker inside `LOOPX_TMPDIR` would be removed with the tmpdir before the harness can read it after settlement. The recommended strategy is: each driver computes a unique per-run marker path outside any tmpdir (e.g., `<test-tmp>/run-<uuid>-tmpdir.txt`) and passes it to the script via `RunOptions.env` (e.g., `{ env: { OBSERVED_TMPDIR_MARKER: "<abs-path>" } }`). The script reads `OBSERVED_TMPDIR_MARKER` and writes `$LOOPX_TMPDIR` into that externally-supplied path using `printf '%s' "$LOOPX_TMPDIR" > "$OBSERVED_TMPDIR_MARKER"`. This avoids both (a) the clobbering hazard of a fixed project-relative path shared by both concurrent runs, and (b) the "marker inside tmpdir gets cleaned up" hazard. Launch two `runPromise("ralph", { env: { OBSERVED_TMPDIR_MARKER: <unique-path-per-run> }, ... })` invocations in parallel against the same project's cwd. After **both** promises settle, read the two marker files to capture each run's `LOOPX_TMPDIR` value. Assert: (a) both promises resolve, (b) the two captured `LOOPX_TMPDIR` values are distinct strings, (c) both tmpdir paths have been cleaned up after settlement (per SPEC 7.4 cleanup-on-normal-completion — check via `fs.existsSync(tmpdirPath) === false` for each captured path), and (d) the two paths share the same parent directory (`os.tmpdir()` evaluated in the driver process) — proving the tmpdirs are sibling `mkdtemp` results, not e.g. one being nested inside the other. Driver-side care: the two `runPromise` calls must both observe the same `process.env.TMPDIR` snapshot (eager, per SPEC 9.2), so set `TMPDIR` to a per-test isolated parent before the first call and do not mutate it between the two calls. **Do not attempt to read the marker from `LOOPX_TMPDIR/observed-tmpdir.txt` after settlement**: SPEC 7.4's cleanup-on-normal-completion contract removes that path before the harness can read it. An alternative strategy is to read the marker files **before** settlement completes (e.g., by having the script block on a sentinel file before emitting `stop:true`), but the external-marker-path approach above is simpler and more robust. *(Spec 7.4, 9.2, 9.5)*
+- **T-TMP-08b**: Concurrent **CLI `loopx run`** invocations against the **same project** also get distinct tmpdirs. SPEC 7.4's "Concurrent runs are isolated. Each run receives its own distinct directory" applies on the CLI surface as well as the programmatic surface — two parallel `loopx run` processes that share a `.loopx/` and project root must each receive a separate tmpdir. ADR-0004's "parallel `loopx run` invocations do not clobber each other" guarantee speaks to the **CLI** surface most directly: in practice, users run multiple `loopx run` shells concurrently against the same checkout far more commonly than they fan out two `runPromise()` calls in a single Node process. T-TMP-08a pins the contract on the `runPromise()` programmatic surface; T-TMP-08 covers concurrency only across **independent** projects (and its setup does not exercise a project-keyed-tmpdir bug for the CLI surface in the way T-TMP-08a does for the programmatic surface). A buggy implementation that incorrectly keyed CLI tmpdir creation on project root (one tmpdir per project, reused across concurrent CLI runs against the same project) would pass T-TMP-08 (independent projects → distinct project keys → distinct tmpdirs) and T-TMP-08a (programmatic surface uses a different code path) while silently failing on every concurrent CLI invocation against the same checkout. **Setup.** Set up a single project with `.loopx/ralph/index.sh` that observes `LOOPX_TMPDIR` into an external marker file path supplied via the inherited environment (the same external-marker discipline as T-TMP-08a; **the marker file path must be external to `LOOPX_TMPDIR` itself** because SPEC 7.4 requires tmpdir cleanup on normal completion — any marker inside `LOOPX_TMPDIR` would be removed with the tmpdir before the harness can read it after settlement). The script body: `printf '%s' "$LOOPX_TMPDIR" > "$OBSERVED_TMPDIR_MARKER"` followed by an emit of `{"stop":true}`. The driver computes a **unique per-run marker path** outside any tmpdir (e.g., `<test-tmp>/cli-run-<uuid>-tmpdir.txt`) for each of the two CLI invocations. **Drive.** Use Node's `child_process.spawn` to launch two parallel `loopx run -n 1 ralph` child processes against the same project's cwd. For each child, build the inherited environment as `{ ...process.env, OBSERVED_TMPDIR_MARKER: <unique-marker-path-for-this-child>, TMPDIR: <test-isolated-parent> }` — the per-child unique `OBSERVED_TMPDIR_MARKER` is the canonical CLI counterpart to T-TMP-08a's `RunOptions.env` injection (env-var injection on `child_process.spawn`'s `env` option is the CLI-surface analogue, since CLI invocations do not have a `RunOptions.env` channel). **Both children must be spawned before either is awaited** — i.e., issue both `child_process.spawn` calls and capture their `Promise<exitCode>` futures, then `await Promise.all([...])` — to guarantee parallel overlap (sequential spawns followed by individual awaits would not exercise concurrency). Wait for both child processes to exit. Read the two marker files to capture each run's `LOOPX_TMPDIR` value. **Assert.** (a) both child processes exit with code 0, (b) both marker files exist and contain a non-empty `LOOPX_TMPDIR` value (the script ran in each invocation and wrote its observation), (c) the two captured `LOOPX_TMPDIR` values are **distinct strings** — neither CLI invocation reused or clobbered the other's tmpdir, (d) both tmpdir paths have been cleaned up after the children exited (per SPEC 7.4 cleanup-on-normal-completion — `fs.existsSync(tmpdirPath) === false` for each captured path), and (e) the two paths share the same parent directory — the test-isolated `TMPDIR` parent the driver passed to both children — proving the tmpdirs are sibling `mkdtemp` results, not e.g. one being nested inside the other. Driver-side care: set `TMPDIR=<test-isolated-parent>` in each child's inherited environment so both children's `os.tmpdir()` resolves to the same parent (the parallel-test framework may already provide per-test `TMPDIR` isolation; if not, create the parent explicitly via `fs.mkdtemp` in the driver setup). The two child spawns must occur before either is awaited; do not serialize them via `await spawn1; await spawn2` (which would defeat the concurrency requirement). **Do not attempt to read the marker from inside `LOOPX_TMPDIR` after the child exits**: SPEC 7.4's cleanup-on-normal-completion contract removes that path. *(Spec 7.4)*
+- **T-TMP-08c**: Concurrent **`run()`** generator invocations against the **same project** also get distinct tmpdirs. Generator-surface counterpart to T-TMP-08a (`runPromise()`) and T-TMP-08b (CLI). SPEC 7.4's "Concurrent runs are isolated. Each run receives its own distinct directory" applies on the `run()` generator surface as well — two parallel `run()` generators that share a `.loopx/` and project root must each receive a separate tmpdir. The two surfaces have **different snapshot timing** for the inherited-env / tmpdir-parent capture (lazy first-`next()` under `run()` per SPEC 9.1 / 7.4; eager call-site under `runPromise()` per SPEC 9.2 / 7.4) — a buggy implementation that incorrectly cached the tmpdir-parent or shared a single tmpdir across overlapping `run()` generators (e.g., a singleton inadvertently scoped to the module / process rather than the run) could pass T-TMP-08a (different code path on `runPromise()`) and T-TMP-08b (different process per CLI run) while silently failing here. **Setup.** Set up a single project with `.loopx/ralph/index.sh` that observes `LOOPX_TMPDIR` into an external marker file path supplied via `RunOptions.env` (the same external-marker discipline as T-TMP-08a / T-TMP-08b; **the marker file path must be external to `LOOPX_TMPDIR` itself** because SPEC 7.4 requires tmpdir cleanup on normal completion — any marker inside `LOOPX_TMPDIR` would be removed before the harness can read it after settlement). The script body waits for an external **release sentinel** path (also supplied via `RunOptions.env`) before emitting `stop:true`, so both generators are simultaneously in-iteration with `LOOPX_TMPDIR` already created when their tmpdirs are observed. Concretely: `printf '%s' "$LOOPX_TMPDIR" > "$OBSERVED_TMPDIR_MARKER"; while [ ! -f "$RELEASE_SENTINEL" ]; do sleep 0.05; done; printf '%s\n' '{"stop":true}'`. **Drive.** Compute two unique per-run marker paths and a single shared release-sentinel path outside any tmpdir (e.g., `<test-tmp>/run-<uuid>-tmpdir.txt` and `<test-tmp>/release.sentinel`). Set `process.env.TMPDIR` to a per-test isolated parent before either call (so both generators observe the same lazy-snapshot tmpdir parent) and do not mutate it between the two calls. Launch two `run("ralph", { env: { OBSERVED_TMPDIR_MARKER: <path-1>, RELEASE_SENTINEL: <release-path> }, maxIterations: 1 })` generators **concurrently** — call `run()` twice in succession (capturing both generator handles) and then drive both forward in parallel by calling `gen1.next()` and `gen2.next()` in either order without awaiting between the calls (e.g., `const p1 = gen1.next(); const p2 = gen2.next(); …`). Once **both** marker files exist on disk (poll for both before releasing) — confirming both generators have entered iteration with their tmpdirs created — create the shared release sentinel (`fs.writeFileSync(<release-path>, "")`) so both scripts unblock and both generators settle. Drive each generator to settlement (`for await (const _ of gen1) {}` / `for await (const _ of gen2) {}`, or equivalent) and then read each marker file to capture each run's `LOOPX_TMPDIR` value. **Assert.** (a) both generators settle cleanly (no error), (b) both marker files exist and contain a non-empty `LOOPX_TMPDIR` value, (c) the two captured `LOOPX_TMPDIR` values are **distinct strings** — neither generator reused or clobbered the other's tmpdir, (d) both tmpdir paths have been cleaned up after settlement (per SPEC 7.4 cleanup-on-normal-completion — `fs.existsSync(tmpdirPath) === false` for each captured path), and (e) the two paths share the same parent directory — the test-isolated `TMPDIR` parent the driver pinned in `process.env.TMPDIR` before either `run()` call — proving the tmpdirs are sibling `mkdtemp` results, not e.g. one being nested inside the other. Driver-side care: do not mutate `process.env.TMPDIR` between the two `run()` calls (both calls' lazy snapshots must observe the same parent — SPEC 9.1's lazy timing means each generator captures `process.env.TMPDIR` on its own first-`next()`, but the test's invariant is that they both pin the same parent so assertion (e) is observable). **Do not attempt to read the marker from inside `LOOPX_TMPDIR` after settlement**: SPEC 7.4's cleanup-on-normal-completion contract removes that path. Together with T-TMP-08 (independent projects), T-TMP-08a (`runPromise()` same project), and T-TMP-08b (CLI same project), this closes the concurrent-run tmpdir-isolation contract across all four combinations of {independent / same project} × {programmatic generator / promise / CLI} — the four cells the SPEC 7.4 isolation guarantee must hold over. *(Spec 7.4, 9.1, 9.5)*
+- **T-TMP-09**: `LOOPX_TMPDIR` mode is `0700`. After a run starts (and before cleanup), capture the tmpdir path from `observe-env` and `stat` it. Assert the mode bits are exactly `0o700` (owner-only rwx). Use a fixture that records the tmpdir into a marker file but does not remove it before the test's mode check can run — e.g., spawn loopx as a background process, wait for the marker, read tmpdir from it, stat the tmpdir, then allow loopx to complete. *(Spec 7.4)*
+
+##### Not-Created Cases
+
+- **T-TMP-10**: `LOOPX_TMPDIR` is **not** created under CLI `-n 0`. Run `loopx run -n 0 ralph`. Script must not spawn (zero iterations), so observing `LOOPX_TMPDIR` inside a script is impossible — instead, snapshot the set of directories in `os.tmpdir()` matching `loopx-*` before and after the run. Assert: no new `loopx-*` directory was created during the `-n 0` run. *(Spec 7.4)*
+- **T-TMP-11**: `LOOPX_TMPDIR` is **not** created under `runPromise({ maxIterations: 0 })`. Call `runPromise("ralph", { maxIterations: 0 })`. Snapshot `os.tmpdir()` (or the test-isolated tmpdir parent — see section 4.7's tmpdir-block preface) for `loopx-*` entries before and after. Assert no new `loopx-*` directory. Mirrors T-TMP-10 on the `runPromise()` programmatic surface; T-TMP-11a covers the `run()` generator surface. The `runPromise()` / `run()` split is meaningful because the two surfaces have different snapshot timing for the inherited-env / tmpdir-parent capture (eager under `runPromise()` per SPEC 9.2; lazy under `run()` per SPEC 9.1) — a buggy implementation that wired the `maxIterations: 0` early-exit short-circuit before tmpdir creation on only one of the two surfaces would pass on one and fail on the other. *(Spec 7.4, 9.5)*
+- **T-TMP-11a**: `LOOPX_TMPDIR` is **not** created under `run()` generator with `maxIterations: 0`. Generator-surface counterpart to T-TMP-11. SPEC 7.4 says "`maxIterations: 0` early exits ... do not create a tmpdir," and SPEC 9.5 says `maxIterations: 0` "validates and exits without executing any iterations. No `LOOPX_TMPDIR` is created under `maxIterations: 0`." This rule applies to both `run()` and `runPromise()`, but the two surfaces have different snapshot timing (lazy first-`next()` under `run()` per SPEC 9.1; eager call-site under `runPromise()` per SPEC 9.2). A buggy implementation that placed the zero-iteration short-circuit *after* tmpdir creation on the `run()` path while correctly placing it before on the `runPromise()` path would pass T-TMP-11 and fail this test. **Setup.** Place `.loopx/ralph/index.sh` (a minimal valid script — e.g., `printf '%s\n' '{"stop":true}'`); the script must not actually spawn since `maxIterations: 0` short-circuits before iteration begins, but it must exist so any pre-iteration validation that wants to verify target existence can succeed. Set `TMPDIR` to a per-test isolated parent directory (per the section 4.7 tmpdir-block preface) so concurrent test workers do not pollute the negative assertion. **Drive.** `const g = run("ralph", { maxIterations: 0 }); const result = await g.next();` Snapshot the test-isolated `TMPDIR` parent for `loopx-*` entries **before** the `run()` call and **again after `g.next()` resolves**. **Assert.** (a) `result.done === true` — the generator settles immediately on first `next()` without yielding any `Output` (zero iterations means zero yields), (b) no script marker is written (the script body never executed because no child was spawned), and (c) no new `loopx-*` directory exists in the test-isolated `TMPDIR` parent after `g.next()` resolves — the count of `loopx-*` entries is identical to the pre-call snapshot. Together with T-TMP-10 (CLI `-n 0`) and T-TMP-11 (`runPromise()` `maxIterations: 0`), this closes the zero-iteration early-exit branch of "no tmpdir under early exit" across all three execution surfaces. *(Spec 7.4, 9.1, 9.5)*
+- **T-TMP-12**: `LOOPX_TMPDIR` is **not** created when pre-iteration failures fire before tmpdir creation. **Parameterized over fourteen distinct pre-iteration failure modes**, each enumerated as its own concrete sub-case so traceability matrices and implementation-driving coverage do not have to interpret a "repeat for ..." prose clause. Each sub-case follows the same harness shape: configure the failure deterministically, snapshot `os.tmpdir()` (or the test-isolated tmpdir parent — see section 4.7's tmpdir-block preface) for `loopx-*` entries before the call, await the failure path (`runPromise` rejection or `run` first-`next` throw), then snapshot again and assert no new `loopx-*` entry was created during the call. The sub-cases are:
+  - **T-TMP-12-env-file**: env-file load failure. `runPromise("ralph", { envFile: "nonexistent.env" })` — the env-file failure surfaces before tmpdir creation per Spec 7.1 step 2 (env-file loading) ordering ahead of step 6 (tmpdir creation). Assert the rejection is the env-file-load error and no `loopx-*` directory was created during the call.
+  - **T-TMP-12-global-env-unreadable**: unreadable global env file. Per SPEC 8.1 "If the file exists but is unreadable (e.g., permission denied), loopx exits with code 1 and an error message," and per SPEC 7.1 step 2 the global env file is loaded as part of the env-loading step ahead of step 6 (tmpdir creation). Set up an isolated `XDG_CONFIG_HOME` (e.g., `<test-dir>/xdg-config`) so the test does not touch the real user config, write a valid `loopx/env` file under it, then `chmod 000` the file so it exists but is unreadable. Pass `XDG_CONFIG_HOME=<isolated>` via `RunOptions.env` is not sufficient — per SPEC 8.1 "Global env file path resolution ... reads `XDG_CONFIG_HOME` / `HOME` from the inherited environment on the same schedule," and `RunOptions.env` does not affect global env-file path resolution. Therefore the test must inject `XDG_CONFIG_HOME` into the **inherited environment** of the loopx process (i.e., into `process.env` of the test driver before invoking `runPromise`, since `runPromise()` snapshots the inherited env eagerly per SPEC 9.2). Call `runPromise("ralph", { maxIterations: 1 })` against a valid `.loopx/ralph/index.sh`. Assert: (a) the promise rejects with a global-env-file-read error (the test does not pin exact wording — the failure category is the "file exists but is unreadable" error from SPEC 8.1), and (b) no `loopx-*` directory was created during the call under the test-isolated `TMPDIR` parent. Together with T-TMP-12-env-file (local-`-e` env-file failure, which exercises a different code path: explicit user-supplied path missing), this closes the env-loading branch of "pre-tmpdir failures must not create a tmpdir" — both the global-env file branch and the local-env file branch are covered. **Conditional on `process.getuid() !== 0`** (root can read mode-000 files, defeating the unreadable setup).
+  - **T-TMP-12-missing-workflow**: missing workflow. `runPromise("nonexistent-workflow")` against a `.loopx/` that does not contain `nonexistent-workflow`. The missing-workflow target-resolution error surfaces before tmpdir creation per Spec 7.1 step 3 (target resolution) ordering ahead of step 6. Assert the rejection is the missing-workflow error and no `loopx-*` directory was created.
+  - **T-TMP-12-target-validation**: target syntax validation. `runPromise(":script")` (leading-colon target — invalid per SPEC 4.1's target grammar). The target-validation error surfaces before tmpdir creation per Spec 7.1 step 3 (target resolution — parsing the workflow / script portions of the target string) ordering ahead of step 6. Assert the rejection is the target-validation error and no `loopx-*` directory was created.
+  - **T-TMP-12-invalid-maxIterations**: invalid `maxIterations` value. `runPromise("ralph", { maxIterations: -1 })` (negative `maxIterations` — invalid per SPEC 9.5). The option-snapshot error surfaces before tmpdir creation per Spec 9.1 / 9.2's option-snapshot timing rule (snapshot at call site or first `next`, both before pre-iteration work). Assert the rejection is the invalid-`maxIterations` error and no `loopx-*` directory was created. (Renamed from the former `T-TMP-12-options-shape` to reflect that the failure category exercised is per-field `maxIterations` validation, not the wrapper-`options`-shape validation rule from SPEC 9.5; the wrapper-shape branch is exercised separately by T-TMP-12-invalid-options-shape below.)
+  - **T-TMP-12-invalid-options-shape**: invalid `options` argument shape. `runPromise("ralph", null as any)` — per SPEC 9.5 "`options` must be omitted, `undefined`, or a non-null, non-array, non-function object," `null` is rejected as an invalid `options` shape. The option-snapshot error surfaces before tmpdir creation per the same Spec 9.1 / 9.2 option-snapshot timing rule. Assert the rejection is the invalid-`options`-shape error and no `loopx-*` directory was created during the call. Distinct from T-TMP-12-invalid-maxIterations (per-field validation) and T-TMP-12-invalid-env-shape (per-field shape validation): this test pins down the wrapper-shape validation outcome that fires before any per-field reads occur.
+  - **T-TMP-12-invalid-env-shape**: invalid `RunOptions.env` shape. `runPromise("ralph", { env: null as any })` — per SPEC 9.5 `env` "must be omitted, `undefined`, or a non-null, non-array, non-function object whose own enumerable string-keyed entries all have string values." A `null` `env` is rejected as an invalid `env` shape. The option-snapshot error surfaces before tmpdir creation per the same Spec 9.1 / 9.2 option-snapshot timing rule. Assert the rejection is the invalid-`env`-shape error and no `loopx-*` directory was created during the call.
+  - **T-TMP-12-invalid-env-value**: non-string `env` entry value. `runPromise("ralph", { env: { KEY: 42 as any } })` — per SPEC 9.5 "an entry with a non-string value" is captured at call time and surfaced via the standard pre-iteration error path. The option-snapshot error surfaces before tmpdir creation per the same Spec 9.1 / 9.2 timing rule. Assert the rejection is the invalid-`env`-value error and no `loopx-*` directory was created during the call. Together with T-TMP-12-invalid-env-shape, this covers both the wrapper-shape branch and the per-entry-value branch of SPEC 9.5's `env` shape rule — a buggy implementation that validated the env wrapper but did not validate per-entry values would pass T-TMP-12-invalid-env-shape and fail this test, and vice versa.
+  - **T-TMP-12-invalid-signal**: invalid `options.signal`. `runPromise("ralph", { signal: "not-an-AbortSignal" as any })`. The option-snapshot error for the non-`AbortSignal` value surfaces before tmpdir creation per the same Spec 9.1 / 9.2 option-snapshot rule. Assert the rejection is the option-signal-shape error and no `loopx-*` directory was created.
+  - **T-TMP-12-invalid-target**: non-string `target` argument. `runPromise(undefined as any)` against any project. Per SPEC 9.1 / 9.2 "runtime-invalid `target` values (e.g., `undefined`, `null`, `42`, or any non-string) are rejected lazily: `run()` still returns a generator without throwing, and the error is raised on first iteration"; for `runPromise()` the validation surfaces as a rejection. The target-argument-validation failure surfaces before tmpdir creation per Spec 7.1 step 3 (target resolution) ordering ahead of step 6. Assert the rejection is the invalid-`target` error and no `loopx-*` directory was created during the call. Distinct from T-TMP-12-target-validation (which exercises target *syntax* validation against a string target) — this test exercises the *type* validation that rejects a non-string target before any syntax parsing can occur.
+  - **T-TMP-12-invalid-cwd**: non-string `cwd`. `runPromise("ralph", { cwd: 42 as any })`. Per SPEC 9.5 "When present and not `undefined`, [`cwd`] must be a string. A non-string value, or a throwing `cwd` getter, is captured at call time and surfaced via the pre-iteration error path." The option-snapshot error surfaces before tmpdir creation per the same Spec 9.1 / 9.2 timing rule. Assert the rejection is the invalid-`cwd` error and no `loopx-*` directory was created during the call.
+  - **T-TMP-12-invalid-envFile**: non-string `envFile`. `runPromise("ralph", { envFile: 42 as any })`. Per SPEC 9.5 "When present and not `undefined`, [`envFile`] must be a string. A non-string value, or a throwing `envFile` getter, is captured at call time and surfaced via the pre-iteration error path." The option-snapshot error surfaces before tmpdir creation per the same Spec 9.1 / 9.2 timing rule. Assert the rejection is the invalid-`envFile` error and no `loopx-*` directory was created during the call.
+  - **T-TMP-12-programmatic-discovery-missing-loopx**: missing `.loopx/` directory. Call `runPromise("ralph")` against a project root that contains no `.loopx/` subdirectory (the standard missing-`.loopx/` condition mirroring T-CLI-42 / T-DISC-10a / T-SIG-24, applied to the programmatic surface). Per SPEC 7.1 step 1 (discovery) ordering ahead of step 6 (tmpdir creation), the missing-`.loopx/` discovery failure surfaces before tmpdir creation. Assert the rejection references the missing-`.loopx/` discovery error and no `loopx-*` directory was created during the call. Programmatic counterpart to T-TMP-12-cli-discovery's existence sub-path (the CLI test exercises sibling-validation; this test exercises the missing-directory sub-path on the programmatic surface).
+  - **T-TMP-12-programmatic-discovery-validation**: discovery-time global validation failure. Same setup as T-TMP-12-cli-discovery (a valid target workflow `.loopx/ralph/index.sh` alongside a sibling with a fatal validation error — e.g., `.loopx/broken/check.sh` + `.loopx/broken/check.ts` name collision, or `.loopx/-bad-workflow/index.sh` invalid workflow name). Call `runPromise("ralph")`. Per SPEC 5.4 global validation is fatal in run mode, and per SPEC 7.1 the discovery-validation step runs before tmpdir creation. Assert the rejection references the discovery-validation error and no `loopx-*` directory was created during the call. Programmatic counterpart to T-TMP-12-cli-discovery (sibling-validation sub-path).
+
+  Together, the fourteen sub-cases cover the pre-iteration failure modes that fire ahead of tmpdir creation per Spec 7.1 / 8.1 / 8.2 / 9.1 / 9.2 / 9.5 ordering — the env-loading branch (env-file, global-env-unreadable), the target-resolution branch (missing-workflow, target-validation, invalid-target), the option-snapshot branch (invalid-maxIterations, invalid-options-shape, invalid-env-shape, invalid-env-value, invalid-signal, invalid-cwd, invalid-envFile), and the discovery branch on the programmatic surface (programmatic-discovery-missing-loopx, programmatic-discovery-validation). T-TMP-10 (CLI `-n 0`) and T-TMP-11 (programmatic `maxIterations: 0`) cover the early-exit branch separately; T-TMP-12a / T-TMP-12b / T-TMP-12c cover the tmpdir-creation-failure branch where a tmpdir attempt is made but fails. *(Spec 7.4, 7.1, 5.4, 8.1, 8.2, 9.1, 9.2, 9.5)*
+- **T-TMP-12-cli**: `LOOPX_TMPDIR` is **not** created when CLI pre-iteration failures fire before tmpdir creation. SPEC 7.4 applies to the CLI just as to the programmatic API — per SPEC 7.1 step 6, tmpdir creation happens after pre-iteration steps 1–5 (discovery, env loading, target resolution, version check). Pre-iteration failures at steps 1–5 must not create a tmpdir. T-TMP-12 covers the programmatic surface (parameterized over five failure modes); this test adds CLI variants parameterized over five CLI-observable pre-iteration failure modes. Each sub-case follows the same harness shape: snapshot the test-isolated `TMPDIR` parent (following the section 4.7 tmpdir-block preface guidance: set `TMPDIR` to an isolated per-test parent directory so a concurrent-worker `loopx-*` entry does not pollute the assertion) for `loopx-*` entries before the run, run the CLI with the failure configured, then snapshot again and assert no new `loopx-*` entry was created during the run. The sub-cases are:
+  - **T-TMP-12-cli-env-file**: missing env file. Run `loopx run -e nonexistent.env ralph` against a valid `.loopx/ralph/index.sh`. Assert exit code 1, stderr references the missing env file, and no `loopx-*` directory was created under the test-isolated `TMPDIR`. CLI counterpart to T-TMP-12-env-file.
+  - **T-TMP-12-cli-missing-workflow**: missing workflow. Run `loopx run nonexistent-workflow` against a `.loopx/` that does not contain `nonexistent-workflow`. Assert exit code 1, stderr references the missing workflow, and no `loopx-*` directory was created. CLI counterpart to T-TMP-12-missing-workflow.
+  - **T-TMP-12-cli-target-validation**: target syntax validation. Run `loopx run ":script"` (leading-colon target — invalid per SPEC 4.1). Assert exit code 1, stderr references the target-validation error, and no `loopx-*` directory was created. CLI counterpart to T-TMP-12-target-validation.
+  - **T-TMP-12-cli-discovery**: discovery / name-collision failure in a sibling workflow. Set up a valid target workflow `.loopx/ralph/index.sh` alongside a sibling with a fatal validation error (e.g., `.loopx/broken/check.sh` + `.loopx/broken/check.ts` name collision, or `.loopx/-bad-workflow/index.sh` invalid workflow name). Run `loopx run ralph`. Assert exit code 1, stderr references the discovery validation error, and no `loopx-*` directory was created. Per SPEC 5.4: global validation is fatal in run mode, so the target-workflow run fails before tmpdir creation.
+  - **T-TMP-12-cli-global-env-unreadable**: unreadable global env file. Per SPEC 8.1 ("If the file exists but is unreadable ... loopx exits with code 1") and SPEC 7.1 step 2 (env-file loading runs ahead of tmpdir creation), an unreadable global env file must surface as a CLI exit 1 before tmpdir creation. T-TMP-12-global-env-unreadable covers the same failure mode on the programmatic surface; this test closes the CLI surface gap. Set up an isolated `XDG_CONFIG_HOME` (e.g., `<test-dir>/xdg-config`), write a valid `loopx/env` file under it, then `chmod 000` the file (the same fixture pattern as T-TMP-12-global-env-unreadable; injected into the CLI process's inherited environment, not via `RunOptions.env`). Run `loopx run -n 1 ralph` against a valid `.loopx/ralph/index.sh`. Assert: (a) exit code 1, (b) stderr references the unreadable-global-env-file error, and (c) no `loopx-*` directory was created under the test-isolated `TMPDIR`. CLI counterpart to T-TMP-12-global-env-unreadable. **Conditional on `process.getuid() !== 0`** (root can read mode-000 files).
+
+  Together with T-TMP-12a (CLI tmpdir-creation-failure with `mkdtemp` failure), these five sub-cases cover the CLI-observable pre-iteration failure modes that must not create a tmpdir. Tmpdir-creation-failure cases where the attempt fails partway through (identity-capture / mode-secure failure) are covered by T-TMP-12d / T-TMP-12e via the section 1.4 `LOOPX_TEST_TMPDIR_FAULT` seam. *(Spec 7.4, 7.1, 5.4, 8.1, 8.2)*
+- **T-TMP-12-cli-usage**: `LOOPX_TMPDIR` is **not** created when CLI invocations fail at the **parser** layer or short-circuit on **`-h` / `--help`** — i.e., neither path enters the SPEC 7.1 *execution* pre-iteration sequence, so step 6 (tmpdir creation) is never reached. SPEC 7.4 says tmpdir creation runs only "for each `loopx run` ... invocation **that reaches execution**". Parser-error invocations never enter execution at all; run-help short-circuits exit before execution begins, but per SPEC 11.2 they may still perform non-fatal workflow discovery/validation for display purposes — that display-side discovery is separate from the execution pre-iteration sequence and does not create a `LOOPX_TMPDIR`. T-TMP-12-cli covers execution-side pre-iteration runtime failures (env-loading, target-resolution, discovery); this test covers the *parser-level* and *help-short-circuit* boundary that precedes execution. **Parameterized over six CLI surfaces**, each following the same harness shape: snapshot the test-isolated `TMPDIR` parent for `loopx-*` entries before the run, run the CLI invocation, then snapshot again and assert no new `loopx-*` entry was created during the run. The sub-cases are:
+  - **T-TMP-12-cli-no-target**: `loopx run` (no positional, no flags) → usage error, exit 1. The parser rejects the missing-target invocation per SPEC 4.1 / 12; the pre-iteration sequence never starts. Assert exit code 1, stderr surfaces a usage error, and no `loopx-*` directory was created under the test-isolated `TMPDIR`. CLI counterpart to the parser-level gap that T-TMP-12-cli does not exercise (it requires the parser to succeed and reach pre-iteration).
+  - **T-TMP-12-cli-unknown-flag**: `loopx run --unknown ralph` against a valid `.loopx/ralph/index.sh` → usage error, exit 1. The parser rejects `--unknown` per T-CLI-35 before reaching pre-iteration. Assert exit code 1, stderr surfaces the unrecognized-flag error, and no `loopx-*` directory was created.
+  - **T-TMP-12-cli-duplicate-n**: `loopx run -n 3 -n 5 ralph` against a valid `.loopx/ralph/index.sh` → usage error, exit 1 (per T-CLI-20a). Duplicate `-n` is rejected at the parser layer before pre-iteration. Assert exit code 1, stderr surfaces the duplicate-flag error, and no `loopx-*` directory was created.
+  - **T-TMP-12-cli-duplicate-e**: `loopx run -e a.env -e b.env ralph` against a valid `.loopx/ralph/index.sh` → usage error, exit 1 (per T-CLI-20b). Duplicate `-e` is rejected at the parser layer before pre-iteration (and before either env-file is loaded — so even though the parser-rejection path could in principle have side-effected env-file loading on the first `-e`, it must not, and no tmpdir is created either way). Assert exit code 1, stderr surfaces the duplicate-flag error, and no `loopx-*` directory was created.
+  - **T-TMP-12-cli-help-with-unknown**: `loopx run -h --unknown` (per T-CLI-54) → run-help short-circuit, exit 0. The `-h` short-circuit does not enter the execution pre-iteration sequence: no env-file loading, no target resolution, no version check, no tmpdir creation, no script spawn. Per SPEC 11.2, run help may still perform non-fatal workflow discovery/validation for display purposes, and `-e` / target syntax / `--` / extra positionals / `name=value` tokens are ignored unconditionally for execution and parser-error purposes — but none of that creates a `LOOPX_TMPDIR`. Assert exit code 0, stdout contains run-help, and no `loopx-*` directory was created. This pins the "help short-circuit creates no tmpdir" guarantee that T-CLI-54 (which only asserts exit 0 and help output) does not directly exercise. The test does **not** assert "no discovery" — SPEC 11.2 explicitly permits it.
+  - **T-TMP-12-cli-help-with-dashdash**: `loopx run --help -- ralph` (per T-CLI-69a) → run-help short-circuit, exit 0. Same short-circuit semantics as T-TMP-12-cli-help-with-unknown (run help does not enter the execution pre-iteration sequence, though SPEC 11.2 non-fatal run-help discovery may still occur), but with the long-form `--help` and a `--` token that would otherwise be a usage error. Assert exit code 0, stdout contains run-help, and no `loopx-*` directory was created.
+
+  Together, the six sub-cases pin down that neither parser-level usage errors nor `-h` / `--help` short-circuits create a `loopx-*` tmpdir — closing the pre-pre-iteration boundary that T-TMP-12-cli (steps 1–5 failures) and T-TMP-12a (step 6 failure) do not exercise. A buggy implementation that created the tmpdir eagerly during command parsing (or that ran the pre-iteration sequence "speculatively" before parser validation) would fail one or more sub-cases. *(Spec 7.4, 7.1, 4.1, 4.2, 11.2, 12)*
+
+##### Tmpdir Creation Failure
+
+SPEC 7.2 / 7.4 define behavior when any step of the tmpdir creation sequence fails: loopx does not spawn any child, the CLI exits with code 1, `run()` throws on first `next()`, and `runPromise()` rejects. Best-effort cleanup runs on any partial directory. These tests exercise a real `mkdtemp` failure by setting the tmpdir parent (`TMPDIR`) to a path whose parent directory is unwritable.
+
+- **T-TMP-12a**: CLI — tmpdir creation failure causes exit 1 with no child spawned. Create `.loopx/ralph/index.sh` that writes a marker file on execution. Create an unwritable directory (e.g., `/tmp/loopx-unwritable-parent/` with mode `0500` under non-root). Set `TMPDIR=/tmp/loopx-unwritable-parent/nonexistent` in the CLI's inherited environment (the parent is unwritable, so `mkdtemp` will fail). Run `loopx run -n 1 ralph`. Assert: (a) exit code 1, (b) stderr contains a tmpdir-creation-failure error message, (c) the `ralph:index` marker file does **not** exist (no child was spawned), (d) no `loopx-*` directory was created under the unwritable parent, and (e) **stderr contains no cleanup-related warning** — per SPEC 7.4, when `mkdtemp` itself fails "no path exists, so no cleanup is needed"; the cleanup-warning path is therefore not entered, and a buggy implementation that emitted a spurious cleanup warning despite there being no path to clean up would fail (e). The cleanup-warning text is implementation-defined per SPEC 7.4; the assertion checks for absence of any cleanup-related stderr line (e.g., no occurrence of cleanup-warning marker substrings the implementation uses elsewhere — the test pairs with T-TMP-12d2 / T-TMP-12e2 which assert *presence* of exactly one cleanup warning, so the negative form here uses the same detection predicate inverted). **Conditional on `process.getuid() !== 0`.** *(Spec 7.2, 7.4)*
+- **T-TMP-12b**: `run()` — tmpdir creation failure throws on first `next()`. Same unwritable-parent setup as T-TMP-12a. Call `run("ralph", { maxIterations: 1 })` from a driver whose inherited `process.env.TMPDIR` points at the unwritable path. Await `gen.next()`. Assert: (a) the generator throws with a tmpdir-creation-failure error, (b) the `ralph:index` marker file does not exist, (c) snapshot `os.tmpdir()` before/after — no `loopx-*` directory created, and (d) **stderr contains no cleanup-related warning** — per SPEC 7.4, when `mkdtemp` itself fails "no path exists, so no cleanup is needed"; the cleanup-warning path is therefore not entered, and a buggy implementation that emitted a spurious cleanup warning despite there being no path to clean up would fail (d). Uses the same cleanup-warning marker-line detection predicate as T-TMP-12a's (e) — `LOOPX_TEST_CLEANUP_WARNING\t…`-prefixed stderr lines, inverted to assert zero. Mirrors T-TMP-12a's (e) negative assertion on the `run()` surface, closing the same SPEC §7.4 "no path exists, so no cleanup is needed" guarantee across all three creation-failure surfaces (CLI / `run()` / `runPromise()`). **Conditional on `process.getuid() !== 0`.** *(Spec 7.2, 7.4, 9.1)*
+- **T-TMP-12c**: `runPromise()` — tmpdir creation failure rejects. Same unwritable-parent setup. Call `runPromise("ralph", { maxIterations: 1 })`. Assert: (a) the promise rejects with a tmpdir-creation-failure error, (b) no child was spawned (marker file absent), (c) snapshot the test-isolated `TMPDIR` parent before/after — no `loopx-*` directory created, and (d) **stderr contains no cleanup-related warning** — same SPEC §7.4 "no path exists, so no cleanup is needed" rationale as T-TMP-12a / T-TMP-12b; the cleanup-warning path is not entered when `mkdtemp` itself fails. Uses the same cleanup-warning marker-line detection predicate as T-TMP-12a's (e), inverted to assert zero. Mirrors T-TMP-12a's (e) negative assertion on the `runPromise()` surface, closing the same SPEC §7.4 guarantee across all three creation-failure surfaces. **Conditional on `process.getuid() !== 0`.** *(Spec 7.2, 7.4, 9.2)*
+- **T-TMP-12f**: Starting-workflow version check runs **before** tmpdir creation (SPEC 7.1 step 5 before step 6). SPEC 7.1 pre-iteration ordering: step 5 is the starting workflow's version check, step 6 is `LOOPX_TMPDIR` creation. When step 5 produces a warning *and* step 6 fails, loopx should still emit the version warning (because the version check ran to completion before the tmpdir-creation attempt), not silently skip it because step 6 errored. Configure an unwritable tmpdir parent as in T-TMP-12a (a `TMPDIR` whose parent is mode 0500 so `mkdtemp` fails) **and** create `.loopx/ralph/index.sh` with a `.loopx/ralph/package.json` declaring a `loopx` dependency range not satisfied by the running version (e.g., `{ "dependencies": { "loopx": ">=999.0.0" } }`). The script writes a marker file on execution. Run `loopx run -n 1 ralph` (CLI) under this environment. Assert: (a) exit code 1 (tmpdir creation failure is the terminal error per SPEC 7.2), (b) stderr contains both the version-mismatch warning (from step 5) *and* the tmpdir-creation-failure error message (from step 6) — the version warning appears even though step 6 fails, proving step 5 ran to completion first, (c) no child was spawned (marker file absent — step 7 is not reached), and (d) no `loopx-*` directory was created under the unwritable parent. Ordering is observable via the presence of the version warning in the failure output; SPEC 7.1's step ordering directly implies it. **Conditional on `process.getuid() !== 0`.** *(Spec 7.1, 7.2, 7.4, 3.2)*
+- **T-TMP-12f2**: Starting-workflow `package.json` invalid-JSON warning runs **before** tmpdir creation. SPEC 7.1 step 5 enumerates the version check as the trigger for `package.json` failure-mode warnings (per SPEC 3.2 — invalid JSON is one of the four enumerated `package.json` failure modes alongside unsatisfied range / unreadable file / invalid semver). T-TMP-12f covers the unsatisfied-range branch in this ordering; this test extends the same ordering proof to the **invalid-JSON** branch. Configure an unwritable tmpdir parent as in T-TMP-12a, **and** create `.loopx/ralph/index.sh` with a `.loopx/ralph/package.json` containing **invalid JSON** (e.g., `{broken`). The script writes a marker file on execution. Run `loopx run -n 1 ralph` (CLI) under this environment. Assert: (a) exit code 1 (tmpdir creation failure is the terminal error), (b) stderr contains both the **invalid-JSON warning** for `ralph` (from step 5's `package.json` failure-mode handling per SPEC 3.2) *and* the tmpdir-creation-failure error message (from step 6) — the invalid-JSON warning appears even though step 6 fails, proving step 5 ran to completion first, (c) no child was spawned (marker file absent), and (d) no `loopx-*` directory was created under the unwritable parent. Together with T-TMP-12f (unsatisfied range), this proves the step-5-before-step-6 ordering holds across multiple SPEC 3.2 `package.json` failure-mode warning branches, not just the version-mismatch case. **Conditional on `process.getuid() !== 0`.** *(Spec 7.1, 7.2, 7.4, 3.2)*
+- **T-TMP-12f3**: Starting-workflow `package.json` invalid-semver-range warning runs **before** tmpdir creation. Same ordering proof as T-TMP-12f / T-TMP-12f2 applied to the **invalid-semver-range** branch of SPEC 3.2's `package.json` failure modes. Configure an unwritable tmpdir parent as in T-TMP-12a, **and** create `.loopx/ralph/index.sh` with a `.loopx/ralph/package.json` containing valid JSON but an invalid semver range (e.g., `{ "dependencies": { "loopx": "not-a-range!!!" } }`). The script writes a marker file on execution. Run `loopx run -n 1 ralph` (CLI) under this environment. Assert: (a) exit code 1, (b) stderr contains both the **invalid-semver warning** for `ralph` (from step 5's SPEC 3.2 invalid-semver-range failure-mode handling) *and* the tmpdir-creation-failure error message (from step 6), (c) no child was spawned, and (d) no `loopx-*` directory was created under the unwritable parent. Together with T-TMP-12f, T-TMP-12f2, and T-TMP-12f4, this completes the step-5-before-step-6 ordering coverage across the four normatively-warning SPEC 3.2 `package.json` failure-mode branches that fire as part of the starting-workflow version check (unsatisfied range, invalid JSON, invalid semver range, unreadable `package.json`). **Conditional on `process.getuid() !== 0`.** *(Spec 7.1, 7.2, 7.4, 3.2)*
+- **T-TMP-12f4**: Starting-workflow **unreadable** `package.json` warning runs **before** tmpdir creation. Same ordering proof as T-TMP-12f / T-TMP-12f2 / T-TMP-12f3 applied to the **unreadable** branch of SPEC 3.2's `package.json` failure modes (the fourth normatively-warning branch alongside unsatisfied range, invalid JSON, and invalid semver range). SPEC 3.2 explicitly enumerates "Unreadable `package.json` (e.g., permission denied): A warning is printed to stderr. The version check is skipped (treated as no version declared). Execution / installation proceeds." — and ADR-0004 makes the SPEC 7.1 step 5 → step 6 ordering of the version check ahead of `LOOPX_TMPDIR` creation normative. T-TMP-12f / T-TMP-12f2 / T-TMP-12f3 prove the ordering for the other three SPEC 3.2 warning branches; this test pins down the unreadable-`package.json` branch so a buggy implementation that routed the unreadable-file warning through a different, ordering-blind code path (e.g., a synchronous `fs.readFileSync` whose `EACCES` was caught and warned later than steps 1–5 ran) would be caught. Configure an unwritable tmpdir parent as in T-TMP-12a (a `TMPDIR` whose parent is mode 0500 so `mkdtemp` fails) **and** create `.loopx/ralph/index.sh` with a `.loopx/ralph/package.json` containing valid content (e.g., `{ "dependencies": { "loopx": "*" } }`) and then `chmod 000` the `package.json` so it exists but is unreadable. The script writes a marker file on execution. Run `loopx run -n 1 ralph` (CLI) under this environment. Assert: (a) exit code 1 (tmpdir creation failure is the terminal error per SPEC 7.2), (b) stderr contains both the **unreadable-`package.json` warning** for `ralph` (from step 5's SPEC 3.2 unreadable-file failure-mode handling) *and* the tmpdir-creation-failure error message (from step 6) — the unreadable-file warning appears even though step 6 fails, proving step 5 ran to completion first, (c) no child was spawned (marker file absent — step 7 is not reached), and (d) no `loopx-*` directory was created under the unwritable parent. Together with T-TMP-12f / T-TMP-12f2 / T-TMP-12f3, this closes the step-5-before-step-6 ordering coverage across all four normatively-warning SPEC 3.2 `package.json` failure-mode branches; the unreadable-file branch is no longer left as an implicit corollary of T-VER-07's general unreadable-`package.json`-warning behavior. **Conditional on `process.getuid() !== 0`** (root can read mode-000 files, defeating the unreadable setup; root can also write to mode-0500 directories, defeating the unwritable-parent setup — one conditional covers both). *(Spec 7.1, 7.2, 7.4, 3.2)*
+- **T-TMP-12g**: `run()` — starting-workflow version check runs **before** tmpdir creation (programmatic-surface counterpart to T-TMP-12f / T-TMP-12f2 / T-TMP-12f3 / T-TMP-12f4). SPEC 7.1's pre-iteration ordering applies on the programmatic surface as well as the CLI: step 5 (workflow version check) runs ahead of step 6 (`LOOPX_TMPDIR` creation), so a workflow `package.json` warning emitted by step 5 must surface even when step 6 fails. T-TMP-12f / T-TMP-12f2 / T-TMP-12f3 / T-TMP-12f4 pin down this ordering on the CLI surface across the four SPEC 3.2 warning branches; this test mirrors that proof on the `run()` surface, **parameterized over the same four branches**: **(i) unsatisfied range** — `.loopx/ralph/package.json` declares `{ "dependencies": { "loopx": ">=999.0.0" } }`; **(ii) invalid JSON** — `.loopx/ralph/package.json` contains `{broken`; **(iii) invalid semver range** — `.loopx/ralph/package.json` contains `{ "dependencies": { "loopx": "not-a-range!!!" } }`; **(iv) unreadable `package.json`** — valid content `chmod 000`'d. Each variant has a valid `.loopx/ralph/index.sh` that writes a marker file on execution. Configure an unwritable tmpdir parent as in T-TMP-12b (a `TMPDIR` whose parent is mode 0500 so `mkdtemp` fails). For each variant, drive: `const gen = run("ralph", { maxIterations: 1 }); let thrown; try { await gen.next(); } catch (e) { thrown = e; }` Assert (per variant): (a) `thrown` is the tmpdir-creation-failure error (the terminal error per SPEC 7.2 / 9.1), (b) **stderr contains the `package.json` warning text for that variant** (the version-mismatch / invalid-JSON / invalid-semver / unreadable-`package.json` warning surfaces on stderr — proving step 5 ran to completion before step 6 attempted `mkdtemp`), (c) no child was spawned (marker file absent — step 7 is not reached), and (d) no `loopx-*` directory was created under the unwritable parent. Variant (iv) is **conditional on `process.getuid() !== 0`**; the unwritable-`TMPDIR` setup is also **conditional on `process.getuid() !== 0`** (one conditional covers both for variant (iv); for variants (i)–(iii) only the unwritable-parent conditional applies). This test closes the CLI-vs-programmatic parity gap that T-TMP-12f / T-TMP-12f2 / T-TMP-12f3 / T-TMP-12f4 leave on the `run()` surface. A buggy implementation that ran step 5 ahead of step 6 on the CLI surface (passing T-TMP-12f / T-TMP-12f2 / T-TMP-12f3 / T-TMP-12f4) but reordered the steps on the programmatic surface would fail (b) on each variant here. *(Spec 7.1, 7.2, 7.4, 3.2, 9.1)*
+- **T-TMP-12h**: `runPromise()` — starting-workflow version check runs **before** tmpdir creation. `runPromise()` counterpart to T-TMP-12g; same parameterization over the four SPEC 3.2 warning branches and the same unwritable-parent setup. For each variant, drive: `const p = runPromise("ralph", { maxIterations: 1 }); let rejection; try { await p; } catch (e) { rejection = e; }` Assert (per variant): (a) `rejection` is the tmpdir-creation-failure error (the terminal error per SPEC 7.2 / 9.2), (b) **stderr contains the `package.json` warning text for that variant**, (c) no child was spawned, and (d) no `loopx-*` directory was created under the unwritable parent. Variant (iv) **conditional on `process.getuid() !== 0`**. Together with T-TMP-12g (`run()` surface) and T-TMP-12f / T-TMP-12f2 / T-TMP-12f3 / T-TMP-12f4 (CLI surface), this closes the SPEC 7.1 step 5 → step 6 ordering coverage across all three execution surfaces and all four SPEC 3.2 `package.json` warning branches. *(Spec 7.1, 7.2, 7.4, 3.2, 9.2)*
+
+##### Tmpdir Creation Sub-step Coverage
+
+SPEC 7.4 "Creation order" normatively specifies three sub-steps and distinct behavior when each one fails:
+
+1. `mkdtemp` itself fails → no path exists, no cleanup needed.
+2. Identity capture fails (after `mkdtemp` succeeded) → loopx attempts a single non-recursive `rmdir` on the path, outside the race-resistant guarantee.
+3. Mode-securing fails (after `mkdtemp` and identity capture succeeded) → full identity-fingerprint cleanup-safety routine runs.
+
+T-TMP-12a / T-TMP-12b / T-TMP-12c cover sub-step 1 (`mkdtemp` failure) by configuring an unwritable parent. T-TMP-12d / T-TMP-12e cover sub-steps 2 and 3 deterministically via the section 1.4 `LOOPX_TEST_TMPDIR_FAULT` seam (success path of the creation-failure cleanup). T-TMP-12d2 covers the cleanup-failure-during-creation-failure-handling axis for sub-step 2 via the compound `identity-capture-fail-rmdir-fail` seam value. T-TMP-12e2 / T-TMP-12e3 cover the cleanup-failure-during-creation-failure-handling axis for sub-step 3's full cleanup-safety routine via the `mode-secure-fail` × `recursive-remove-fail` and `mode-secure-fail` × `lstat-fail` seam compositions respectively (the two cleanup-safety failure branches reachable from creation-failure handling per SPEC 7.4 — top-level `lstat` failure and rule-4 recursive-removal failure on the identity-matched partial directory). The third cleanup-safety failure branch — rule-2 symlink `unlink` failure — is not reachable from creation-failure handling under `mode-secure-fail` because the partial directory is never a symlink (see section 1.4's reachability note for `mode-secure-fail` × `symlink-unlink-fail`); deterministic coverage of that branch within creation-failure handling would require an additional seam that swaps the partial directory for a symlink between identity capture and the cleanup-safety dispatch, which is documented as a known gap rather than claimed coverage.
+
+- **T-TMP-12d**: Identity capture failure (sub-step 2 of SPEC 7.4's creation order). Set `NODE_ENV=test` and `LOOPX_TEST_TMPDIR_FAULT=identity-capture-fail` in the loopx process's inherited environment so that `mkdtemp` succeeds but the identity-capture stat fails (per the section 1.4 seam contract). Set `TMPDIR=<test-isolated-parent>` so the partial-directory observation is bounded to a single parent the test owns. **Parameterize over the three execution surfaces** (CLI / `run()` / `runPromise()`) — each surface follows the same harness shape as T-TMP-12a / T-TMP-12b / T-TMP-12c respectively. Each variant has a valid `.loopx/ralph/index.sh` that writes a marker file on execution. Snapshot the test-isolated `TMPDIR` parent for `loopx-*` entries before the run. For each surface, drive the standard tmpdir-creation-failure path: (CLI) `loopx run -n 1 ralph`; (`run()`) `const gen = run("ralph", { maxIterations: 1 }); await gen.next();` (expecting throw); (`runPromise()`) `await runPromise("ralph", { maxIterations: 1 })` (expecting reject). Assert per surface: (a) the surface-appropriate terminal failure surfaces (CLI exit 1 with stderr tmpdir-creation-failure error / generator throws tmpdir-creation-failure error / promise rejects with tmpdir-creation-failure error), (b) the `ralph:index` marker file does **not** exist (no child spawned — step 7 not reached), (c) **no `loopx-*` directory remains** under the test-isolated `TMPDIR` parent after the run — per SPEC 7.4 sub-step 2, loopx attempts a single non-recursive `rmdir` on the path created by `mkdtemp`, and since the partial directory is empty (no nested entries are created between `mkdtemp` and the simulated stat-failure), `rmdir` succeeds. A buggy implementation that skipped cleanup of the partial directory would leave the empty `loopx-*` directory behind and fail (c), and (d) **stderr contains no cleanup-related warning** — per SPEC 7.4, the cleanup-failure-during-creation-failure-handling warning fires only when the creation-failure-handling cleanup itself fails ("If `rmdir` fails, loopx emits a single stderr warning"); on the success-`rmdir` branch exercised here, the cleanup completed cleanly and no warning is normative. The cleanup-warning text is implementation-defined per SPEC 7.4; the negative assertion uses the same detection predicate as T-TMP-12d2's positive cleanup-warning assertion, inverted. A buggy implementation that emitted a spurious warning even on the success-`rmdir` path (e.g., logging unconditionally before checking the `rmdir` result) would fail (d). *(Spec 7.4)*
+- **T-TMP-12e**: Mode-securing failure (sub-step 3 of SPEC 7.4's creation order). Set `NODE_ENV=test` and `LOOPX_TEST_TMPDIR_FAULT=mode-secure-fail` so that `mkdtemp` and identity capture both succeed but mode-securing fails (per the section 1.4 seam contract). Set `TMPDIR=<test-isolated-parent>`. **Parameterize over the three execution surfaces** (CLI / `run()` / `runPromise()`) using the same harness shape as T-TMP-12d. Each variant has a valid `.loopx/ralph/index.sh` that writes a marker file. Snapshot the test-isolated `TMPDIR` parent for `loopx-*` entries before the run. Drive the standard tmpdir-creation-failure path on each surface. Assert per surface: (a) the surface-appropriate terminal failure surfaces (CLI exit 1 / generator throws / promise rejects, all with tmpdir-creation-failure error text), (b) the `ralph:index` marker does **not** exist, (c) **no `loopx-*` directory remains** under the test-isolated `TMPDIR` parent — per SPEC 7.4 sub-step 3, the full identity-fingerprint cleanup-safety routine runs on the partial directory; the directory's identity matches loopx's captured fingerprint, so the cleanup-safety routine recursively removes it under rule 4. A buggy implementation that skipped cleanup of the partial directory or that took the narrow `rmdir`-only path of sub-step 2 (which would fail if the partial directory had any nested entries) would leave the partial `loopx-*` directory behind and fail (c), and (d) **stderr contains no cleanup-related warning** — per SPEC 7.4, the cleanup-failure-during-creation-failure-handling warning fires only when the cleanup-safety routine itself fails (top-level `lstat` failure, case-2 `unlink` failure, or case-4 recursive-removal failure); on the success path exercised here (recursive removal under rule 4 succeeds), no warning is normative. The negative assertion uses the same detection predicate as T-TMP-12e2's positive cleanup-warning assertion, inverted. A buggy implementation that emitted a spurious warning even on the success path of the cleanup-safety routine would fail (d). *(Spec 7.4)*
+- **T-TMP-12d2**: Identity-capture failure followed by `rmdir` failure during creation-failure cleanup. SPEC 7.4 specifies: "If `rmdir` fails, loopx emits a single stderr warning and leaves the path in place." The cleanup-failure-during-creation-failure axis is normatively specified but has no direct coverage; T-TMP-12d covers the success-`rmdir` path (the identity-capture failure scenario), and this test pins down the failed-`rmdir` companion case. Set `NODE_ENV=test` and `LOOPX_TEST_TMPDIR_FAULT=identity-capture-fail-rmdir-fail` so that `mkdtemp` succeeds, identity capture fails, and the subsequent single non-recursive `rmdir` itself fails with `EACCES` (per the section 1.4 seam contract). Set `TMPDIR=<test-isolated-parent>`. **Parameterize over the three execution surfaces** (CLI / `run()` / `runPromise()`) using the same harness shape as T-TMP-12d. Each variant has a valid `.loopx/ralph/index.sh` that writes a marker file. Snapshot the test-isolated `TMPDIR` parent for `loopx-*` entries before the run. Drive the standard tmpdir-creation-failure path on each surface. Assert per surface: (a) the surface-appropriate terminal failure surfaces with the **original tmpdir-creation-failure error text** — not the `rmdir` cleanup failure, since SPEC 7.4 specifies the cleanup-failure warning "does not mask the original creation error". The CLI exits 1, the generator throws, the promise rejects, and the surfaced error reports the creation failure (e.g., the simulated `EACCES` from identity capture or an equivalent creation-failure phrasing); (b) **stderr contains exactly one cleanup-related warning** for the `rmdir` failure, on top of the creation-failure error reporting — per SPEC 7.4 "emit one warning, do not mask the original creation error" combined with "Per-cleanup-attempt warning cardinality is at most one"; (c) the `ralph:index` marker does **not** exist (no child spawned); and (d) the partial `loopx-*` directory **remains** under the test-isolated `TMPDIR` parent (the empty directory created by `mkdtemp` was not removed because the `rmdir` failed; SPEC 7.4 says loopx "leaves the path in place" on `rmdir` failure). The harness's fixture-cleanup step removes the partial directory after the assertions. A buggy implementation that masked the creation error with the `rmdir` failure would fail (a); an implementation that emitted no warning or two warnings would fail (b); an implementation that retried or recursively removed the partial directory after the `rmdir` failure would fail (d). *(Spec 7.4)*
+- **T-TMP-12e2**: Mode-securing failure followed by recursive-remove failure during cleanup-safety. Companion to T-TMP-12d2 for the mode-secure-failure axis. SPEC 7.4: "Mode-securing fails (after `mkdtemp` and identity capture succeeded): loopx runs the full cleanup-safety routine above, with the recorded identity fingerprint in hand"; and "Cleanup failure during creation-failure handling emits at most one warning but does not mask the original creation error". T-TMP-12e covers the success-cleanup-safety path; this test pins down the failed-recursive-remove companion case. Set `NODE_ENV=test`, `LOOPX_TEST_TMPDIR_FAULT=mode-secure-fail`, **and** `LOOPX_TEST_CLEANUP_FAULT=recursive-remove-fail` so that `mkdtemp` and identity capture both succeed, mode-securing fails, the full cleanup-safety routine runs (rule 4 — identity matches), and the recursive removal itself fails with `EACCES` (per the section 1.4 seam contract — the `recursive-remove-fail` seam applies whenever the cleanup-safety routine reaches rule 4, including the creation-failure-handling invocation). Set `TMPDIR=<test-isolated-parent>`. **Parameterize over the three execution surfaces** (CLI / `run()` / `runPromise()`) using the same harness shape as T-TMP-12e. Each variant has a valid `.loopx/ralph/index.sh` that writes a marker file. Snapshot the test-isolated `TMPDIR` parent for `loopx-*` entries before the run. Drive the standard tmpdir-creation-failure path on each surface. Assert per surface: (a) the surface-appropriate terminal failure surfaces with the **original tmpdir-creation-failure error text** — the recursive-remove failure does not mask the creation error, per SPEC 7.4. The CLI exits 1, the generator throws, the promise rejects, and the error reports the creation failure (e.g., the simulated `EACCES` from mode-securing); (b) **stderr contains exactly one cleanup-related warning** for the recursive-remove failure — SPEC 7.4 cleanup-warning cardinality is one, and the creation-failure error is separate from the cleanup warning; (c) the `ralph:index` marker does **not** exist; and (d) the partial `loopx-*` directory (or whatever residual remains after the simulated recursive-remove failure) is left in place under the test-isolated `TMPDIR` parent — SPEC 7.4 "no further changes" applies after the cleanup-warning is emitted. The exact disk state is implementation-defined per the recursive-remove seam contract (the failure point within the walk is implementation-defined); the harness's fixture-cleanup step removes any leftover content. A buggy implementation that masked the creation error with the cleanup failure would fail (a); an implementation that emitted no warning, two warnings, or attempted retry would fail (b). *(Spec 7.4)*
+- **T-TMP-12e3**: Mode-securing failure followed by top-level `lstat` failure during cleanup-safety. Companion to T-TMP-12e2 for the second cleanup-safety failure branch reachable from creation-failure handling. SPEC 7.4 specifies that when mode-securing fails "loopx runs the full cleanup-safety routine above, with the recorded identity fingerprint in hand"; the cleanup-safety routine begins with a top-level `lstat` to dispatch on path type. SPEC 7.4: "If the top-level `lstat` fails for any reason other than ENOENT, the `unlink` in case 2 fails, or the recursive removal in case 4 fails, loopx emits a single stderr warning and makes no further changes." T-TMP-12e2 pins down the rule-4 recursive-removal-failure branch; this test pins down the top-level-`lstat`-failure branch on the same composition. Set `NODE_ENV=test`, `LOOPX_TEST_TMPDIR_FAULT=mode-secure-fail`, **and** `LOOPX_TEST_CLEANUP_FAULT=lstat-fail` so that `mkdtemp` and identity capture both succeed, mode-securing fails, the full cleanup-safety routine starts, and the top-level `lstat` itself fails with `EACCES` (per the section 1.4 seam contract — the `lstat-fail` seam applies whenever the cleanup-safety routine runs, including the creation-failure-handling invocation; the seam fires unconditionally on the top-level `lstat` because that step runs before any rule-dispatch decision). Set `TMPDIR=<test-isolated-parent>`. **Parameterize over the three execution surfaces** (CLI / `run()` / `runPromise()`) using the same harness shape as T-TMP-12e2. Each variant has a valid `.loopx/ralph/index.sh` that writes a marker file. Snapshot the test-isolated `TMPDIR` parent for `loopx-*` entries before the run. Drive the standard tmpdir-creation-failure path on each surface. Assert per surface: (a) the surface-appropriate terminal failure surfaces with the **original tmpdir-creation-failure error text** — the `lstat` failure does not mask the creation error, per SPEC 7.4 "does not mask the original creation error". The CLI exits 1, the generator throws, the promise rejects, and the error reports the creation failure (e.g., the simulated `EACCES` from mode-securing); (b) **stderr contains exactly one cleanup-related warning** for the `lstat` failure — SPEC 7.4 cleanup-warning cardinality is at most one per cleanup attempt, and the creation-failure error is separate from the cleanup warning; (c) the `ralph:index` marker does **not** exist (no child spawned); and (d) the partial `loopx-*` directory remains under the test-isolated `TMPDIR` parent — SPEC 7.4 "no further changes" applies once the `lstat` fails, so the cleanup-safety routine does not proceed to rule dispatch, and the partial directory created by `mkdtemp` is left in place. The harness's fixture-cleanup step removes the residual directory after the assertions. A buggy implementation that masked the creation error with the `lstat` failure would fail (a); an implementation that emitted no warning, multiple warnings, or attempted to proceed past the `lstat` failure to rule dispatch would fail (b)/(d). Together with T-TMP-12e2 (rule-4 recursive-remove failure), this completes deterministic coverage of the two cleanup-safety failure branches reachable from creation-failure handling under `mode-secure-fail`; the rule-2 symlink-unlink-failure branch is documented as a known gap in the section preamble (the partial directory is never a symlink, so rule 2 dispatch is unreachable without an additional seam). *(Spec 7.4)*
+
+##### Cleanup Triggers
+
+- **T-TMP-13**: Cleanup on normal completion (`stop:true`). `.loopx/ralph/index.sh` observes `LOOPX_TMPDIR`, writes `$LOOPX_TMPDIR/file.txt`, then outputs `stop:true`. Run CLI. Parse the tmpdir path from the marker. Assert: after loopx exits (exit 0), the tmpdir no longer exists. *(Spec 7.4)*
+- **T-TMP-13a**: `runPromise()` cleanup on normal completion (`stop:true`). Programmatic-API counterpart to T-TMP-13. Same fixture (observes `LOOPX_TMPDIR` into a marker, writes a file inside, emits `stop:true`). Call `runPromise("ralph", { maxIterations: 5 })` (or similar — the loop halts on `stop:true` before the limit). After the promise resolves, read the tmpdir path from the marker and assert it no longer exists on disk. T-TMP-13 pins down CLI cleanup; T-TMP-13b pins down `run()` generator natural-settlement cleanup; T-TMP-22 / T-TMP-22a / T-TMP-22b cover `run()` generator-cancellation cleanup; but normal `runPromise()` resolution-path cleanup is not otherwise directly pinned down. A buggy implementation that cleaned up under CLI and `run()` cancellation paths but skipped cleanup when `runPromise()` resolves normally would pass existing tests and fail this one. *(Spec 7.4, 9.2)*
+- **T-TMP-13b**: `run()` generator cleanup on natural settlement after `stop:true`. Generator-surface counterpart to T-TMP-13 (CLI) and T-TMP-13a (`runPromise`). SPEC 7.4's "Cleanup triggers" list applies to all three surfaces, but cleanup under `run()` driven to natural settlement on a `stop:true` is not separately pinned down: T-TMP-13a covers `runPromise()` resolution; T-TMP-22 / T-TMP-22a / T-TMP-22b cover `run()` cancellation paths (`break`, `.return()`, `.throw()`); T-TMP-23 / T-TMP-24 cover `run()` settlement on `maxIterations` reached. None of these is the simple "script emits `stop:true`, generator is driven to natural settlement, tmpdir cleanup runs" path. A buggy implementation that handled `runPromise()`-resolution cleanup and CLI cleanup but skipped cleanup when `run()` settled naturally on `stop:true` would pass T-TMP-13 / T-TMP-13a / T-TMP-22* / T-TMP-23 / T-TMP-24 and fail this test. Same fixture as T-TMP-13 / T-TMP-13a (`.loopx/ralph/index.sh` observes `LOOPX_TMPDIR` into an external marker, writes a file inside `$LOOPX_TMPDIR`, then emits `stop:true`). Drive: `const gen = run("ralph", { maxIterations: 5 }); for await (const _ of gen) { /* drain */ }` — the `for await` consumes the single yielded output and then drives settlement when the generator returns `{ done: true }` after observing `stop:true`. Equivalently, drive via `gen.next()` until `next()` returns `{ done: true }`. After the loop / final `next()` settles, read the tmpdir path from the external marker and assert it no longer exists on disk. Use an external marker path (not inside `LOOPX_TMPDIR`) so the marker survives cleanup for the post-settlement read. *(Spec 7.4, 9.1)*
+- **T-TMP-14**: Cleanup on normal completion (`-n` reached). Same fixture but no `stop:true`; run with `-n 1`. Assert the tmpdir is removed after loopx exits 0. *(Spec 7.4)*
+- **T-TMP-14a**: `runPromise()` cleanup on `maxIterations` reached. Programmatic-API counterpart to T-TMP-14. Fixture observes `LOOPX_TMPDIR` but emits no `stop:true` or goto — the loop resets between iterations and hits the `maxIterations` bound. Call `runPromise("ralph", { maxIterations: 1 })`. After the promise resolves (with a single-entry output array), read the tmpdir path from the marker and assert it no longer exists. This closes the normal-`runPromise()`-cleanup gap for the iteration-limit settlement path (paired with T-TMP-13a for the `stop:true` settlement path). *(Spec 7.4, 9.2)*
+- **T-TMP-15**: Cleanup on non-zero script exit. Script observes `LOOPX_TMPDIR` into a marker, then `exit 1`. Assert: loopx exits 1, and the tmpdir captured in the marker no longer exists. *(Spec 7.4)*
+- **T-TMP-15a**: `runPromise()` cleanup on non-zero script exit. Programmatic counterpart to T-TMP-15. SPEC 7.4's "Cleanup triggers" list includes "Non-zero script exit" — cleanup must run across all surfaces, not only the CLI. T-TMP-15 covers the CLI exit-1 path; T-TMP-19 and T-TMP-20 cover abort- and consumer-cancellation-driven cleanup on programmatic surfaces; no existing test explicitly pins down the ordinary non-zero-exit cleanup path on `runPromise()`. Same fixture as T-TMP-15 (`.loopx/ralph/index.sh` observes `LOOPX_TMPDIR` into a marker outside the tmpdir, then `exit 1`). Call `runPromise("ralph", { maxIterations: 1 })`. Assert: (a) the promise rejects with a script-failure / non-zero-exit error (per SPEC 9.3), (b) the tmpdir path recorded in the marker no longer exists on disk — cleanup ran before the rejection surfaced (per SPEC 7.4 "Cleanup runs before the generator throws or the promise rejects" / SPEC 9.3 "Cleanup ordering is observable"). Use an external marker path (not inside `LOOPX_TMPDIR`) so the marker survives cleanup for the post-settlement read. *(Spec 7.4, 9.2, 9.3)*
+- **T-TMP-15b**: `run()` cleanup on non-zero script exit. Generator-surface counterpart to T-TMP-15a. Same fixture. Drive: `const gen = run("ralph", { maxIterations: 1 }); let thrown; try { for await (const _ of gen) {} } catch (e) { thrown = e; }`. Assert: (a) the generator threw a script-failure / non-zero-exit error (the `for await` exited via rejection), (b) the tmpdir path recorded in the marker no longer exists — cleanup ran before the throw surfaced. Together with T-TMP-15 (CLI) and T-TMP-15a (`runPromise`), this closes the non-zero-script-exit cleanup coverage across all three surfaces. *(Spec 7.4, 9.1, 9.3)*
+- **T-TMP-16**: Cleanup on invalid goto (missing-workflow branch). Script emits `goto:"nonexistent-workflow:script"`. Assert: loopx exits 1, tmpdir (captured from a prior `LOOPX_TMPDIR` observation) removed. This exercises a syntactically valid but semantically invalid target (the workflow does not exist in the cached discovery results); the malformed-goto (target-syntax violation) branch is covered separately by T-TMP-16b. *(Spec 7.4)*
+- **T-TMP-16a**: Cleanup on goto resolving to a missing script in an existing workflow. Set up `.loopx/ralph/index.sh` that observes `LOOPX_TMPDIR` into a marker and emits `{"goto":"other:missing"}`. Set up `.loopx/other/index.sh` (any valid script — the target workflow exists, but the `missing` script does not). Run `loopx run -n 2 ralph`. Assert: (a) exit code 1, (b) stderr mentions the missing script `missing` in workflow `other`, (c) the tmpdir path recorded in the marker has been removed from disk. Per SPEC 7.4 "Cleanup triggers", cleanup must run on "missing workflow or script during `goto` resolution." T-TMP-16 covers the missing-workflow branch; this test pins down the missing-script branch separately, since SPEC 7.4 enumerates both as distinct cleanup triggers and a buggy implementation could plausibly handle one but not the other. *(Spec 7.4, 7.2, 4.1)*
+- **T-TMP-16c**: `runPromise()` cleanup on missing-workflow goto resolution. Programmatic counterpart to T-TMP-16. Same fixture as T-TMP-16 (script observes `LOOPX_TMPDIR` into an external marker and emits `{"goto":"nonexistent-workflow:script"}`). Call `runPromise("ralph", { maxIterations: 2 })`. Assert: (a) the promise rejects with a missing-workflow error, (b) the tmpdir path recorded in the marker no longer exists. This pins down the "missing workflow during goto resolution" cleanup trigger on the `runPromise()` surface, mirroring T-TMP-16 on the CLI. *(Spec 7.4, 9.2, 9.3)*
+- **T-TMP-16d**: `runPromise()` cleanup on missing-script goto resolution. Programmatic counterpart to T-TMP-16a. Same fixture as T-TMP-16a. Call `runPromise("ralph", { maxIterations: 2 })`. Assert: (a) the promise rejects with a missing-script error, (b) the tmpdir path recorded in the marker no longer exists. *(Spec 7.4, 9.2, 9.3)*
+- **T-TMP-16e**: `run()` cleanup on missing-workflow goto resolution. Generator-surface counterpart to T-TMP-16c. Same fixture; drive via `for await` until the rejection surfaces; assert the tmpdir path no longer exists. *(Spec 7.4, 9.1, 9.3)*
+- **T-TMP-16f**: `run()` cleanup on missing-script goto resolution. Generator-surface counterpart to T-TMP-16d. Same fixture; drive via `for await`; assert tmpdir removed. Together with T-TMP-16 / T-TMP-16a (CLI), T-TMP-16b (malformed-goto, three surfaces), T-TMP-16c/16d (`runPromise`), and T-TMP-16e/16f (`run()`), the missing-workflow / missing-script / malformed-goto cleanup triggers are pinned down across all three surfaces. *(Spec 7.4, 9.1, 9.3)*
+- **T-TMP-16g**: Cleanup on bare-name `goto` resolving to a missing script in the **current** workflow (CLI). T-TMP-16a covers the qualified-target form `{"goto":"other:missing"}` where the target workflow exists but the named script does not — the missing-script branch is reached via cross-workflow resolution. SPEC 4.1 also accepts bare-name `goto` values (a script in the current workflow per section 2.2: "a bare name is a script in the current workflow"), and a bare name that resolves to a missing script in the **same** workflow exercises a structurally distinct lookup path: the resolver does not consult the workflow registry at all, only the current workflow's script set. A buggy implementation that handled the missing-script branch correctly under cross-workflow resolution but missed cleanup on the same-workflow lookup path (e.g., short-circuited cleanup when the workflow-resolution step was skipped) would pass T-TMP-16a and fail this test. Set up `.loopx/ralph/index.sh` that observes `LOOPX_TMPDIR` into a marker file (path external to the tmpdir, so it survives cleanup) and emits `{"goto":"missing"}` (bare name — `missing` is a script-name reference into the **current** workflow `ralph`, not a workflow-name reference). The `ralph` workflow contains only `index.sh`; no `missing` script exists. Run `loopx run -n 2 ralph` (CLI). Assert: (a) exit code 1, (b) stderr mentions the missing script `missing` in workflow `ralph`, and (c) the tmpdir path recorded in the marker has been removed from disk. Per SPEC 7.4: "Cleanup triggers ... missing workflow or script during `goto` resolution" — this clause covers both qualified and bare resolution paths; this test pins down the bare-name path on the CLI surface. *(Spec 7.4, 7.2, 4.1, 2.2)*
+- **T-TMP-16h**: `runPromise()` cleanup on bare-name `goto` resolving to a missing script in the current workflow. Programmatic counterpart to T-TMP-16g. Same fixture as T-TMP-16g (`.loopx/ralph/index.sh` observes `LOOPX_TMPDIR` into an external marker and emits `{"goto":"missing"}`; no `missing` script exists in `ralph`). Call `runPromise("ralph", { maxIterations: 2 })`. Assert: (a) the promise rejects with a missing-script error referencing `missing` in workflow `ralph`, and (b) the tmpdir path recorded in the marker no longer exists. Mirrors T-TMP-16d (qualified missing-script on `runPromise()`) on the bare-name lookup path. *(Spec 7.4, 9.2, 9.3, 2.2)*
+- **T-TMP-16i**: `run()` cleanup on bare-name `goto` resolving to a missing script in the current workflow. Generator-surface counterpart to T-TMP-16g / T-TMP-16h. Same fixture. Drive via `for await` until the rejection surfaces; assert (a) the generator throws a missing-script error referencing `missing` in workflow `ralph`, and (b) the tmpdir path recorded in the marker no longer exists. Together with T-TMP-16g (CLI) and T-TMP-16h (`runPromise()`), this closes the bare-name missing-script cleanup branch across all three surfaces — complementary to T-TMP-16a / 16d / 16f on the qualified-target form. *(Spec 7.4, 9.1, 9.3, 2.2)*
+- **T-TMP-16b**: Cleanup on truly malformed goto (target-syntax violation). SPEC 7.4's "invalid `goto` target" cleanup trigger covers both the semantic-invalidity cases (missing workflow / missing script — covered by T-TMP-16 / T-TMP-16a) and the **syntactic-invalidity** cases enumerated by SPEC 4.1's target-validation rules (empty string, bare colon, leading colon, trailing colon, multiple colons, name-restriction violations). T-TMP-16 uses `"nonexistent-workflow:script"` which has **valid syntax** but an unresolvable target — it does not exercise the target-syntax-rejection path (SPEC 4.1's target validation at step 12a of SPEC 7.1's loop). This test pins down tmpdir cleanup on the distinct target-syntax-rejection branch. Set up `.loopx/ralph/index.sh` that observes `LOOPX_TMPDIR` into a marker and emits `{"goto":"a:b:c"}` (multiple colons — violates SPEC 4.1's "at most one colon" rule). Run `loopx run -n 2 ralph` (CLI). Assert: (a) exit code 1, (b) stderr mentions the invalid target syntax / multiple-colons error (distinct from "workflow not found" phrasing — the failure must be about the target shape, not target resolution), and (c) the tmpdir path recorded in the marker has been removed from disk. Per SPEC 7.4: "Cleanup triggers ... invalid `goto` target" — and SPEC 7.2: "If `goto` contains an invalid target string (section 4.1) ... loopx prints an error message to stderr and exits with code 1. `LOOPX_TMPDIR` cleanup runs before exit." **Programmatic counterparts:** (i) `run("ralph")` — same fixture, drive `const gen = run("ralph"); await gen.next(); await expect(gen.next()).rejects.toThrow(/multiple colons|invalid target/)` and then assert the tmpdir was cleaned up before the throw surfaced; (ii) `runPromise("ralph", { maxIterations: 2 })` — same fixture, assert the promise rejects with the target-syntax error and the tmpdir was cleaned up before the rejection. Together with T-TMP-16 (missing-workflow) and T-TMP-16a (missing-script), this closes the three enumerated sub-branches of SPEC 7.4's "invalid `goto` target" cleanup trigger across the CLI, `run()`, and `runPromise()` surfaces. *(Spec 7.4, 7.2, 4.1, 9.1, 9.2)*
+- **T-TMP-16j**: Cleanup on `goto` whose target violates the SPEC 4.1 **name-restriction pattern** (distinct from the delimiter-syntax violations covered by T-TMP-16b). SPEC 4.1's target-validation rules enumerate two structurally distinct families of syntactic invalidity: (i) **delimiter-syntax violations** (empty string, bare colon, leading colon, trailing colon, multiple colons) — covered by T-TMP-16b's `"a:b:c"` fixture, and (ii) **name-restriction violations** — the workflow portion and the script portion (if present) must each match `[a-zA-Z0-9_][a-zA-Z0-9_-]*`, so a leading dash, an interior dot, an interior space, or any other character outside the pattern in either portion is a target-validation error. T-TMP-16b's multi-colon fixture is rejected at the delimiter-counting stage and never reaches name-pattern matching; a buggy implementation that wired up cleanup correctly on the delimiter-syntax branch but missed it on the name-restriction branch (e.g., dispatched the two validation steps through different error-emission paths and only one of them ran cleanup) would pass T-TMP-16b and fail this test. Set up `.loopx/ralph/index.sh` that observes `LOOPX_TMPDIR` into a marker (path external to the tmpdir, so it survives cleanup) and emits `{"goto":"-bad"}` — the bare target `-bad` has zero colons (so the delimiter-syntax checks pass), but the workflow-name portion `-bad` begins with `-`, violating the `[a-zA-Z0-9_]` first-character requirement of SPEC 4.1's name-restriction pattern. Run `loopx run -n 2 ralph` (CLI). Assert: (a) exit code 1, (b) stderr mentions the invalid target / name-restriction violation (distinct from both "workflow not found" phrasing — the failure must be about the target shape, not target resolution — and from T-TMP-16b's "multiple colons" / "delimiter" phrasing), and (c) the tmpdir path recorded in the marker has been removed from disk. **Programmatic counterparts:** (i) `runPromise("ralph", { maxIterations: 2 })` — same fixture, assert the promise rejects with the name-restriction / target-syntax error and the tmpdir was cleaned up before the rejection; (ii) `run("ralph")` — same fixture, drive `const gen = run("ralph"); await gen.next(); await expect(gen.next()).rejects.toThrow(/invalid target|name restriction/)` and assert the tmpdir was cleaned up before the throw surfaced. Together with T-TMP-16b (delimiter-syntax violation), this closes both syntactic-invalidity families enumerated by SPEC 4.1, complementing T-TMP-16 / T-TMP-16a / T-TMP-16c–f / T-TMP-16g–i (semantic-invalidity branches) on the cleanup-trigger axis. *(Spec 7.4, 7.2, 4.1, 9.1, 9.2)*
+- **T-TMP-17**: Cleanup on SIGINT. Use `runCLIWithSignal`. Fixture observes `LOOPX_TMPDIR` into marker, writes "ready" to stderr, then sleeps. Harness `waitForStderr("ready")`, reads tmpdir from marker, sends SIGINT. Assert: loopx exits 130, and the tmpdir is removed. *(Spec 7.4, 7.3)*
+- **T-TMP-18**: Cleanup on SIGTERM. Same as T-TMP-17 but SIGTERM and exit 143. *(Spec 7.4, 7.3)*
+- **T-TMP-18a**: CLI signal escalation followed by tmpdir cleanup. SPEC 7.3 specifies that the signal is forwarded to the active child process group, that loopx waits ~5 seconds and then sends SIGKILL if the group has not exited, and that "When `LOOPX_TMPDIR` has been created, cleanup runs after any active child process group has exited (per the grace period above, including SIGKILL escalation) and before loopx exits with the signal's code." T-SIG-05 covers the SIGKILL-escalation contract for a SIGTERM-trapping child but does not assert tmpdir cleanup; T-TMP-17 / T-TMP-18 cover tmpdir cleanup on signal but not under SIGKILL escalation (the child terminates promptly without trapping the signal). This test pins down the **combined** contract: SIGKILL escalation **and** tmpdir cleanup on the same run. Set up `.loopx/ralph/index.sh` that (1) observes `LOOPX_TMPDIR` and writes the path to a marker file, (2) installs a SIGTERM trap that ignores the signal (`trap '' TERM`), (3) writes `"ready"` to stderr, then (4) sleeps indefinitely (`while true; do sleep 1; done`). Run `loopx run -n 1 ralph` via `runCLIWithSignal`. Wait for `"ready"` on stderr, read the tmpdir path from the marker file, then send SIGTERM to loopx. Record `start = Date.now()`, await loopx exit, record `end = Date.now()`. Assert: (a) `end - start` is within a ~4–7 second tolerance window — the grace-period wait before SIGKILL escalation took effect (matches T-SIG-05's ~5-second tolerance), (b) loopx exits with code 143 (128 + 15 for SIGTERM, the originally-forwarded signal — not 137, even though the CHILD was killed via SIGKILL, because loopx itself surfaces the original signal it observed, not the escalation signal it sent to the child), (c) the active child process group has been terminated (the script's PID, captured before the trap installation via a separate marker, no longer appears in the process table — verifiable via `kill -0 <pid>` returning non-zero), and (d) the tmpdir path read from the marker **no longer exists on disk** — cleanup ran after the SIGKILL escalation completed and before loopx exited, per SPEC 7.4's "after any active child process group has exited (per the grace period above, including SIGKILL escalation) and before loopx exits with the signal's code." Together with T-SIG-05 (escalation timing without tmpdir assertion) and T-TMP-17 / T-TMP-18 (tmpdir cleanup without escalation), this closes the SPEC 7.3 / 7.4 escalation × cleanup combined contract — proving that an implementation that ran cleanup *before* waiting out the grace period (i.e., before the child actually exits) would not satisfy the post-grace-period ordering, and that an implementation that skipped cleanup after escalation would leak the tmpdir. **`@flaky-retry(3)` due to the real-time 5-second wait**, matching T-SIG-05 and T-INST-116c. *(Spec 7.3, 7.4)*
+- **T-TMP-18b**: CLI signal escalation followed by tmpdir cleanup — SIGINT parity. SIGINT counterpart to T-TMP-18a. SPEC 7.3 names "SIGINT / SIGTERM" together as the signals subject to the active-child grace-period + SIGKILL-escalation rule, and SPEC 7.4's tmpdir-cleanup-after-escalation rule applies symmetrically to both. T-TMP-18a covers the SIGTERM × escalation × tmpdir-cleanup combined contract; T-SIG-05a covers the SIGINT escalation contract without asserting tmpdir cleanup; T-TMP-17 covers the SIGINT cleanup contract without escalation. None of these covers the **combined** SIGINT × escalation × tmpdir-cleanup contract — a buggy implementation that escalated cleanly under SIGTERM but special-cased SIGINT (e.g., skipping the grace period for SIGINT, or skipping cleanup after a SIGINT-driven escalation) would pass T-TMP-18a, T-SIG-05a, and T-TMP-17 individually and fail this test. Set up `.loopx/ralph/index.sh` identically to T-TMP-18a but with the trap installed for **SIGINT** instead of SIGTERM (`trap '' INT`) — i.e., (1) observes `LOOPX_TMPDIR` into a marker, (2) installs `trap '' INT`, (3) writes `"ready"` to stderr, then (4) sleeps indefinitely. Run `loopx run -n 1 ralph` via `runCLIWithSignal`. Wait for `"ready"` on stderr, read the tmpdir path from the marker file, then send **SIGINT** to loopx. Record `start = Date.now()`, await loopx exit, record `end = Date.now()`. Assert: (a) `end - start` is within a ~4–7 second tolerance window — the grace-period wait before SIGKILL escalation took effect, matching T-TMP-18a's tolerance, (b) loopx exits with code **130** (128 + 2 for SIGINT, the originally-forwarded signal — not 137 from the SIGKILL escalation), (c) the active child process group has been terminated (the script's PID, captured before the trap installation, no longer appears in the process table — verifiable via `kill -0 <pid>` returning non-zero), and (d) the tmpdir path read from the marker **no longer exists on disk** — cleanup ran after the SIGKILL escalation completed and before loopx exited, identical contract to T-TMP-18a's (d). Together with T-TMP-18a (SIGTERM), this closes the SPEC 7.3 / 7.4 escalation × cleanup × signal-symmetry combined contract. **`@flaky-retry(3)` due to the real-time 5-second wait**, matching T-TMP-18a and T-SIG-05a. *(Spec 7.3, 7.4)*
+- **T-TMP-19**: Cleanup on programmatic `AbortSignal` abort. `const c = new AbortController(); const gen = run("ralph", { signal: c.signal }); const out = await gen.next(); c.abort();` where the script observed `LOOPX_TMPDIR` during its first iteration. Await the next `gen.next()` (expected to throw the abort error). Assert: tmpdir is removed before the thrown error surfaces — read the tmpdir path from the marker *after* the throw to confirm, or check during a `try { await gen.next() } catch {}` block followed by a `fs.existsSync(tmpdir)` check. *(Spec 7.4, 9.1, 9.5)*
+- **T-TMP-20**: Cleanup on generator cancellation via `.return()` while the first `next()` is pending. Fixture: `.loopx/ralph/index.sh` writes its `LOOPX_TMPDIR` into a marker file using a fresh `fs.writeFileSync` call (via an equivalent bash helper: `printf '%s' "$LOOPX_TMPDIR" > $markerPath`), writes `"ready"` to stderr, then blocks in a long-running operation — the script never yields (never calls `output()` / `loopx output`) and never exits. Drive with: `const gen = run("ralph"); const nextP = gen.next(); waitForStderr("ready"); await gen.return(undefined); await nextP.catch(() => {});` Assert: (a) the active child process group is terminated (PID from the `write-pid-to-file` marker no longer exists), (b) the tmpdir path read from the marker is removed, (c) the generator settles cleanly (the awaited `.return()` resolves to `{ done: true, value: undefined }` without throwing). Consumer-driven cancellation via `.return()` is a silent, clean completion per SPEC 9.1 — the loop body was entered (so this is not the pre-first-`next()` carve-out), but the active child is terminated and tmpdir cleanup runs before settlement. *(Spec 7.4, 9.1)*
+- **T-TMP-21**: Cleanup on generator cancellation via `.throw()` while the first `next()` is pending, with process-group termination and tmpdir cleanup. Same fixture as T-TMP-20 (observes `LOOPX_TMPDIR`, writes PID, writes "ready" to stderr, then blocks indefinitely). Drive with: `const gen = run("ralph"); const nextP = gen.next(); waitForStderr("ready"); const throwP = gen.throw(new Error("consumer-err")).catch((e) => ({ rejected: e }));` Assert: (a) the active child process group is terminated (PID from the `write-pid-to-file` marker no longer exists), (b) the tmpdir path read from the marker is removed, and (c) the generator reaches a settled state — either `throwP` resolves to `{ done: true }` (silent completion), or it rejects (with either the consumer-supplied error or a conforming cancellation error). The generator must not be left hanging. Also assert (d) the pending `nextP` promise settles (either resolves or rejects) and does not block indefinitely. **Note:** SPEC 9.1 explicitly documents "silent, clean completion" for consumer-driven cancellation when *no child process is active*; for the active-child `.throw()` case SPEC requires the active child process group to be terminated and no further iterations to start, but does not pin down whether the consumer-supplied error is swallowed vs. surfaced. This test therefore asserts only the process-group-termination + tmpdir-cleanup + settlement contract that SPEC normatively requires; the consumer-error-propagation outcome is intentionally left unspecified to match SPEC's actual guarantees. T-API-09e covers the no-active-child `.throw()` case where SPEC does normatively require silent completion; T-API-09a covers the active-child `.return()` form for comparison. *(Spec 7.4, 9.1)*
+- **T-TMP-22**: Cleanup on `break` after yield. `for await (const o of run("ralph")) { break; }`. The fixture yielded `LOOPX_TMPDIR` via observation into a marker. Assert tmpdir removed after the `for await` block exits. *(Spec 7.4, 9.1)*
+- **T-TMP-22a**: Cleanup on `.return()` after a yielded output, with no child active. Tmpdir-cleanup counterpart to T-API-09d. Fixture: `.loopx/ralph/index.sh` observes `LOOPX_TMPDIR` into a marker file, then emits `{"result":"ok"}` (no goto, no stop — the loop will reset between iterations). Drive: `const gen = run("ralph"); const first = await gen.next(); // first script yielded and exited — no child active; const settled = await gen.return(undefined);` Assert: (a) `first.value` is the first iteration's output, (b) `settled.done === true` (silent completion per SPEC 9.1), and (c) the tmpdir path read from the marker **no longer exists** after `.return()` resolves — cleanup ran before the generator settled, per SPEC 7.4's "Cleanup triggers" list ("Consumer-driven cancellation under `run()` (`break` from `for await`, `.return()` / `.throw()` after first `next()`) — after terminating any active child per section 9.1, before the generator settles"). T-TMP-22 covers the `break` form; this test covers `.return()` on the same no-active-child shape. *(Spec 7.4, 9.1)*
+- **T-TMP-22b**: Cleanup on `.throw()` after a yielded output, with no child active. Tmpdir-cleanup counterpart to T-API-09e. Same fixture as T-TMP-22a. Drive: `const gen = run("ralph"); const first = await gen.next(); const settled = await gen.throw(new Error("consumer-err"));` Assert: (a) `first.value` is the first iteration's output, (b) `settled.done === true` — per SPEC 9.1, `.throw()` on the no-active-child path produces silent completion (the consumer-supplied error is not surfaced), (c) the tmpdir path read from the marker no longer exists after `.throw()` resolves — cleanup ran before settlement even though the consumer passed an error, matching SPEC 7.4's "Consumer-driven cancellation ... before the generator settles" rule. Together with T-TMP-22 (`break`) and T-TMP-22a (`.return()`), this completes tmpdir-cleanup coverage across all three no-active-child consumer-cancellation surfaces. *(Spec 7.4, 9.1)*
+- **T-TMP-22c**: Cleanup on `.return()` after the **final** yielded output (`maxIterations: 1`). Tmpdir-cleanup on the post-final-yield / pre-settlement boundary for `.return()`. Same fixture as T-TMP-22a but with `{ maxIterations: 1 }`. Drive: `const gen = run("ralph", { maxIterations: 1 }); const { value } = await gen.next(); // final yielded value, the iteration limit has been reached; const settled = await gen.return(undefined);`. Assert: (a) `value` is the final iteration's output, (b) `settled.done === true`, and (c) the tmpdir path read from the marker **no longer exists** after `.return()` resolves. SPEC 7.4 / 9.1 leave the window between final yield and settlement with tmpdir state implementation-defined (see T-TMP-23's rationale for not asserting existence mid-window), but settlement — whether driven by a subsequent `next()`, a completing `for await`, `.return()`, or `.throw()` — must complete cleanup. T-TMP-23 drives settlement via the post-final `next()`; this test drives it via `.return()` on the same final-yield boundary. *(Spec 7.4, 9.1)*
+- **T-TMP-22d**: Cleanup on `.throw()` after the **final** yielded output (`maxIterations: 1`). Counterpart to T-TMP-22c for `.throw()`. Same fixture; drive: `const { value } = await gen.next(); const settled = await gen.throw(new Error("consumer-err"));`. Assert: (a) `value` is the final iteration's output, (b) `settled.done === true` — `.throw()` arrived after the script that produced the final yield had already exited (no child is active in the post-final-yield window), so SPEC 9.1's no-active-child rule applies and the generator must reach a silent, clean completion (the consumer-supplied error is swallowed, not surfaced — same outcome as T-TMP-22b), and (c) the tmpdir path no longer exists after settlement. The post-final-yield state is "no child active" in the same sense as the between-iterations / `break`-after-yield states already covered by T-TMP-22 / T-TMP-22a / T-TMP-22b — the iteration limit being reached does not change which clause of SPEC 9.1 applies; the active-child-`.throw()` carve-out from T-TMP-21 (where SPEC does not pin the settlement form) does not apply here because no child is active. SPEC 7.4's cleanup trigger ("Consumer-driven cancellation ... before the generator settles") fires on the same silent-completion settlement. *(Spec 7.4, 9.1)*
+- **T-TMP-22e**: Cleanup on `.return()` after a `stop: true`-driven **final** yielded output. SPEC 9.3 enumerates `stop: true` and `maxIterations` reached symmetrically as final-yield triggers; SPEC 7.4's cleanup-trigger list pairs both with cleanup-before-settlement under consumer-driven cancellation. T-TMP-22c covers the `.return()` form on the **`maxIterations`-reached** trigger; T-TMP-24f covers `.return()` on the **`stop: true`** trigger but only for the **abort-races** carve-out (where the abort displaces the consumer's `.return()` and the cleanup-before-settlement is observed alongside an abort-error rejection). The pure consumer-cancellation form on the `stop: true` trigger — `.return()` after the script's `stop: true` final yield with **no abort** — is not covered. The two trigger types share normative outcome (cleanup before settlement, silent completion) but exercise different state-machine transitions inside loopx (`stop: true` settles via the script-emitted halt; `maxIterations` settles via the iteration counter), so a buggy implementation that wired cleanup correctly on one trigger but not the other could pass T-TMP-22c yet fail this test. Set up `.loopx/ralph/index.sh` that observes `LOOPX_TMPDIR` into a marker file (path external to the tmpdir, so it survives cleanup for the post-settlement read), then emits `{"stop":true}` on its first iteration. Drive: `const gen = run("ralph", { maxIterations: 5 }); const first = await gen.next(); /* first.value.stop === true — final yield via stop:true */ const settled = await gen.return(undefined);` Assert: (a) `first.value` is the script's `stop:true` output, (b) `settled.done === true` (silent completion per SPEC 9.1's consumer-driven-cancellation no-active-child rule — the script that produced the final yield has already exited), and (c) the tmpdir path read from the marker **no longer exists** after `.return()` resolves — cleanup ran before the generator settled, matching SPEC 7.4's "Consumer-driven cancellation ... before the generator settles" rule on the `stop: true` final-yield path. Together with T-TMP-22c (`.return()` × `maxIterations`-reached trigger) and T-TMP-22f (`.throw()` × `stop: true` trigger), this completes the consumer-cancellation × final-yield-trigger × {`.return()` / `.throw()`} matrix on the no-abort surface. *(Spec 7.4, 9.1)*
+- **T-TMP-22f**: Cleanup on `.throw()` after a `stop: true`-driven **final** yielded output. Counterpart to T-TMP-22e for `.throw()`. Same fixture as T-TMP-22e (`.loopx/ralph/index.sh` observes `LOOPX_TMPDIR` and emits `{"stop":true}` on the first iteration). Drive: `const gen = run("ralph", { maxIterations: 5 }); const first = await gen.next(); /* first.value.stop === true */ const settled = await gen.throw(new Error("consumer-err"));` Assert: (a) `first.value` is the script's `stop:true` output, (b) `settled.done === true` — `.throw()` arrived after the script that produced the final yield had already exited (no child active), so SPEC 9.1's no-active-child rule produces silent completion (the consumer-supplied error is swallowed, not surfaced — same outcome as T-TMP-22b / T-TMP-22d), and (c) the tmpdir path read from the marker **no longer exists** after `.throw()` resolves — cleanup ran before settlement even though the consumer passed an error, matching SPEC 7.4's "Consumer-driven cancellation ... before the generator settles" rule on the `stop: true` final-yield path. Together with T-TMP-22d (`.throw()` × `maxIterations`-reached trigger) and T-TMP-22e (`.return()` × `stop: true` trigger), this completes the consumer-cancellation × final-yield-trigger × {`.return()` / `.throw()`} matrix on the no-abort surface, mirroring T-TMP-24e / T-TMP-24f / T-TMP-24g's coverage of the abort-races surface. *(Spec 7.4, 9.1)*
+
+##### Final-Yield-vs-Settlement Carve-out
+
+- **T-TMP-23**: After the final yield, cleanup is guaranteed only once the generator settles. `const gen = run("ralph", { maxIterations: 1 });` with fixture that observes `LOOPX_TMPDIR`. Do `const { value } = await gen.next();` — this is the first and final yield. Read tmpdir from marker. **Make no assertion about the tmpdir's existence at this point** — SPEC 7.4 leaves the post-final-yield / pre-settlement cleanup state implementation-defined; "may still exist" is not a testable post-condition (a passing test must establish a definite truth, not a permission). Then call `await gen.next()` (expecting `{ done: true }`). **After settlement, assert tmpdir is removed.** This is the only definite assertion the test makes: settlement triggers cleanup, regardless of how the implementation handled the window between final yield and settlement. This documents Spec 7.4's nuance that abandoning the generator after the final yielded value (without driving settlement) may leak the tmpdir, by proving the converse — that driving settlement removes it. The complementary "leak" claim ("a generator abandoned without settlement leaks the tmpdir") is intentionally **not** asserted, because (a) SPEC 7.4 does not pin down a leak window — an implementation that opportunistically cleans up between final yield and settlement is also conformant — and (b) a leak-window test would be inherently racy under garbage-collected runtimes. *(Spec 7.4, 9.1)*
+- **T-TMP-24**: Cleanup via full `for await` completion. Same fixture as T-TMP-23 but consume via `for await` until the generator completes naturally. Assert tmpdir is removed after the `for await` loop exits — `for await` drives settlement automatically. *(Spec 7.4, 9.1)*
+- **T-TMP-24a**: Abort after the final yield but before settlement still runs tmpdir cleanup before surfacing the abort error. `const c = new AbortController(); const gen = run("ralph", { signal: c.signal, maxIterations: 1 }); const first = await gen.next();` (fixture observed `LOOPX_TMPDIR`). Abort `c`, then `await gen.next()` and expect the abort error. After the throw, assert the tmpdir path recorded by the fixture no longer exists. This is the cleanup-order counterpart to T-API-66. *(Spec 7.4, 9.3)*
+- **T-TMP-24c**: Abort after the final yield but before settlement runs tmpdir cleanup before `gen.return()` surfaces the abort. SPEC 9.3 "Abort after final yield" enumerates `.next()`, `.return()`, and `.throw()` as the three settlement interactions that surface the abort error; SPEC 7.4 pairs each settlement trigger with tmpdir cleanup. T-TMP-24a covers the `.next()` settlement path; this test covers `.return()`. `const c = new AbortController(); const gen = run("ralph", { signal: c.signal, maxIterations: 1 }); const first = await gen.next();` (fixture observes `LOOPX_TMPDIR` during its execution and writes the path to a marker). Abort `c`, then `await expect(gen.return(undefined)).rejects.toThrow(<abort error>)` — expect the `.return()` to reject with the abort error (matching T-API-66a). After the rejection, assert the tmpdir path recorded by the fixture no longer exists on disk — cleanup ran before the abort error surfaced through `.return()`, matching SPEC 7.4's "before the generator settles" rule. This is the cleanup-order counterpart to T-API-66a. *(Spec 7.4, 9.3, 9.1)*
+- **T-TMP-24d**: Abort after the final yield but before settlement runs tmpdir cleanup before `gen.throw()` surfaces the abort. Same structure as T-TMP-24c but with `.throw()` as the settlement trigger. `const c = new AbortController(); const gen = run("ralph", { signal: c.signal, maxIterations: 1 }); const first = await gen.next();` (fixture observes `LOOPX_TMPDIR` during execution). Abort `c`, then `await expect(gen.throw(new Error("consumer-err"))).rejects.toThrow(<abort error>)` — expect the `.throw()` to reject with the **abort error** (the signal displaces the consumer-supplied error per SPEC 9.3's abort-after-final-yield rule, matching T-API-66b). After the rejection, assert the tmpdir path recorded by the fixture no longer exists on disk. Together with T-TMP-24a (`.next()`) and T-TMP-24c (`.return()`), this completes tmpdir-cleanup-before-settlement coverage across all three settlement interactions enumerated in SPEC 9.3's abort-after-final-yield clause for the **`maxIterations`-reached** final-yield trigger. *(Spec 7.4, 9.3, 9.1)*
+- **T-TMP-24e**: Abort after **`stop: true`-driven** final yield runs tmpdir cleanup before `.next()` surfaces the abort. Cleanup-order counterpart to T-API-66c, mirroring T-TMP-24a's relationship to T-API-66. SPEC 9.3 enumerates `stop: true` and `maxIterations` reached symmetrically as final-yield triggers, and SPEC 7.4 pairs each abort-after-final-yield settlement with tmpdir cleanup before the abort surfaces. T-TMP-24a / T-TMP-24c / T-TMP-24d cover the `maxIterations`-reached trigger across the three settlement interactions; this test closes the `stop: true` trigger × `.next()` settlement combination. Set up `.loopx/ralph/index.sh` that observes `LOOPX_TMPDIR` into a marker file (path external to the tmpdir, so it survives cleanup for the post-throw read), then emits `{"stop":true}` on its first iteration. Drive: `const c = new AbortController(); const gen = run("ralph", { signal: c.signal, maxIterations: 5 }); const first = await gen.next(); /* first.value.stop === true */ c.abort(); await expect(gen.next()).rejects.toThrow(<abort error>);` After the rejection, read the tmpdir path from the marker and assert it no longer exists on disk — cleanup ran before the abort surfaced through `.next()`, matching SPEC 7.4's "before the generator throws" rule. *(Spec 7.4, 9.3, 9.1)*
+- **T-TMP-24f**: Abort after **`stop: true`-driven** final yield runs tmpdir cleanup before `.return()` surfaces the abort. Cleanup-order counterpart to T-API-66d. Same fixture as T-TMP-24e. Drive: `const c = new AbortController(); const gen = run("ralph", { signal: c.signal, maxIterations: 5 }); const first = await gen.next(); c.abort(); await expect(gen.return(undefined)).rejects.toThrow(<abort error>);` After the rejection, assert the tmpdir path no longer exists on disk. Together with T-TMP-24e (`.next()`) on the same final-yield trigger, this pins down the cleanup-before-settlement contract for the `.return()` settlement on the `stop: true`-driven path. *(Spec 7.4, 9.3, 9.1)*
+- **T-TMP-24g**: Abort after **`stop: true`-driven** final yield runs tmpdir cleanup before `.throw()` surfaces the abort. Cleanup-order counterpart to T-API-66e. Same fixture as T-TMP-24e. Drive: `const c = new AbortController(); const gen = run("ralph", { signal: c.signal, maxIterations: 5 }); const first = await gen.next(); c.abort(); await expect(gen.throw(new Error("consumer-err"))).rejects.toThrow(<abort error>);` (the abort displaces the consumer-supplied error per SPEC 9.3, matching T-API-66e). After the rejection, assert the tmpdir path no longer exists on disk. Together with T-TMP-24e (`.next()`), T-TMP-24f (`.return()`), T-TMP-24a / T-TMP-24c / T-TMP-24d (the `maxIterations`-reached trigger across the same three settlement interactions), this completes the tmpdir-cleanup-before-settlement coverage matrix across all three settlement interactions × both final-yield triggers (`stop: true` and `maxIterations` reached) enumerated in SPEC 9.3's abort-after-final-yield clause. *(Spec 7.4, 9.3, 9.1)*
+- **T-TMP-24b**: External SIGKILL to loopx itself does not run tmpdir cleanup. Use `runCLIWithSignal` with a fixture that writes both `LOOPX_TMPDIR` and the child PID to marker files, writes `"ready"` to stderr, and then sleeps. After reading the tmpdir path from the marker, send `SIGKILL` to the loopx process itself. Assert: (a) the process terminates due to `SIGKILL`, and (b) the tmpdir path still exists on disk after loopx dies — loopx had no chance to run cleanup. The harness then explicitly kills the orphaned child PID as test cleanup. This covers the SPEC 7.4 "cleanup does not run when loopx itself is killed via SIGKILL" clause. *(Spec 7.4)*
+
+##### Tmpdir Parent Snapshot Timing
+
+**Literal-path expectation (applies to every test in this subsection and to the env-file / `RunOptions.env` tmpdir-parent tests T-TMP-28 / T-TMP-28a / T-TMP-28b / T-TMP-29 / T-TMP-29a–29k).** Test descriptions in this block use illustrative literal paths like `/tmp/loopx-test-parent-A`, `/tmp/loopx-parent-A`, `/tmp/right-parent`, `/tmp/wrong-parent`, etc., for readability. **Each individual test must allocate the actual paths via `fs.mkdtemp(path.join(os.tmpdir(), "loopx-test-parent-"))` (or equivalent per-test mkdtemp helper) at test setup**, then thread the allocated absolute paths through the `TMPDIR` / `TEMP` / `TMP` configuration and the assertions — the literal `/tmp/loopx-...` strings in the descriptions are placeholders, not contract paths. This requirement reinforces the section 4.7 "Test-parent isolation (flakiness guidance — applies suite-wide)" preface for the snapshot-timing block specifically: concurrent test workers must not race on a fixed `/tmp/loopx-...` parent, and stale entries from prior runs must not be miscounted into the snapshot-timing assertions. The "wrong" candidate path (the one loopx must **not** consult, e.g., the env-file value in T-TMP-28 / T-TMP-29 / T-TMP-29a) may be either pre-created via `fs.mkdtemp` or a synthesized non-existent path, since loopx must not consult it; the "right" candidate path (the one loopx **must** consult — typically the inherited-env value) must always be a real `fs.mkdtemp`-allocated directory because loopx's `os.tmpdir()` pass will attempt to `mkdtemp` into it. Test descriptions retain the literal-path notation purely for readability; the test implementation must substitute mkdtemp-allocated paths.
+
+- **T-TMP-25**: CLI — tmpdir parent determined pre-iteration. **Pre-create a writable directory at `/tmp/loopx-test-parent-A/`** before invoking loopx (e.g., via `mkdirSync(parentPath, { recursive: true })` in the test setup), so the tmpdir creation step has a valid parent to `mkdtemp` into. Set `TMPDIR=/tmp/loopx-test-parent-A` in the CLI environment. Run `loopx run -n 1 ralph` with fixture observing `LOOPX_TMPDIR`. Assert the tmpdir lives under `/tmp/loopx-test-parent-A/` — the parent was captured at pre-iteration time from loopx's own inherited env. (Per the literal-path expectation above, the test allocates the parent via `fs.mkdtemp(path.join(os.tmpdir(), "loopx-test-parent-"))` and substitutes the result for the literal `/tmp/loopx-test-parent-A` placeholder in the description.) *(Spec 7.4)*
+- **T-TMP-25a**: Tmpdir parent via `TEMP` when `TMPDIR` is unset. SPEC 7.4 specifies the tmpdir parent is `os.tmpdir()` evaluated in loopx's own process — `os.tmpdir()` documents reading `TMPDIR` / `TEMP` / `TMP` (in platform-conventional order) from `process.env`. This test covers the `TEMP` branch. Pre-create a writable directory (e.g., `/tmp/loopx-temp-env-parent/`). Spawn loopx with its inherited environment configured so `TMPDIR` is **unset**, `TMP` is **unset**, and `TEMP` is set to the pre-created directory. Run `loopx run -n 1 ralph` with fixture observing `LOOPX_TMPDIR`. Assert the tmpdir lives under the `TEMP` directory **iff** the active runtime's `os.tmpdir()` consults `TEMP` in this configuration; otherwise (and as a conservative shared assertion across runtimes) assert that the tmpdir's parent matches `os.tmpdir()` evaluated in a child Node/Bun process spawned with the same inherited environment. This keeps the test honest about runtime variation — on platforms/runtimes where `TEMP` is consulted, the assertion is exact; elsewhere it still proves loopx follows `os.tmpdir()` rather than hard-coding `TMPDIR`. *(Spec 7.4)*
+- **T-TMP-25b**: Tmpdir parent via `TMP` when `TMPDIR` and `TEMP` are unset. Same pattern as T-TMP-25a for the `TMP` branch. Pre-create a writable directory (e.g., `/tmp/loopx-tmp-env-parent/`). Spawn loopx with its inherited environment configured so `TMPDIR` and `TEMP` are **unset** and `TMP` is set to the pre-created directory. Run `loopx run -n 1 ralph` with fixture observing `LOOPX_TMPDIR`. Assert the tmpdir lives under the `TMP` directory **iff** the active runtime's `os.tmpdir()` consults `TMP` in this configuration; otherwise assert the tmpdir's parent matches `os.tmpdir()` evaluated in an identically-configured child process. Together with T-TMP-25 (`TMPDIR` set) and T-TMP-25a (`TEMP` set), this closes the three-variable coverage for `os.tmpdir()` inputs named in SPEC 7.4. *(Spec 7.4)*
+- **T-TMP-26**: `run()` — tmpdir parent captured lazily on first `next()`. **Pre-create both candidate parent directories** (`/tmp/loopx-parent-A/` and `/tmp/loopx-parent-B/`) before driving the test, so whichever the snapshot resolves to is a valid `mkdtemp` target. `process.env.TMPDIR = "/tmp/loopx-parent-A"; const gen = run("ralph", { maxIterations: 1 }); process.env.TMPDIR = "/tmp/loopx-parent-B"; await gen.next();` (script observes `LOOPX_TMPDIR`). Assert: the tmpdir lives under `/tmp/loopx-parent-B` — the mutation between `run()` returning and first `next()` does affect the parent (the snapshot is lazy). *(Spec 7.4, 9.1)*
+- **T-TMP-27**: `runPromise()` — tmpdir parent captured eagerly at call site. **Pre-create both candidate parent directories** (`/tmp/loopx-parent-A/` and `/tmp/loopx-parent-B/`) before driving the test, so whichever the snapshot resolves to is a valid `mkdtemp` target. `process.env.TMPDIR = "/tmp/loopx-parent-A"; const p = runPromise("ralph", { maxIterations: 1 }); process.env.TMPDIR = "/tmp/loopx-parent-B"; await p;` (script observes `LOOPX_TMPDIR`). Assert: the tmpdir lives under `/tmp/loopx-parent-A` — the mutation *after* `runPromise()` returned did not redirect the parent (eager snapshot at call site). *(Spec 7.4, 9.2)*
+- **T-TMP-27a**: `runPromise()` does **not** create `LOOPX_TMPDIR` synchronously before returning — creation happens asynchronously during the pre-iteration sequence after `runPromise()` returns. Per SPEC 9.2: "`LOOPX_TMPDIR` itself is created asynchronously after return, during the same pre-iteration sequence used by the CLI and `run()`." T-TMP-27 covers the eager parent-snapshot half (a synchronous `process.env.TMPDIR` mutation after `runPromise()` returns does not redirect the parent); this test covers the complementary asynchronous-tmpdir-creation half — that the directory itself is not yet on disk when `runPromise()` returns synchronously. **Pre-create a test-isolated parent directory** (e.g., `<test-tmp>/loopx-tmpdir-parent/`). Configure loopx's inherited environment so `os.tmpdir()` resolves to that parent (`TMPDIR=<test-tmp>/loopx-tmpdir-parent`, `TEMP` / `TMP` unset). Drive: snapshot the parent's `loopx-*` entries via `fs.readdirSync(parent).filter(e => e.startsWith("loopx-"))` (call it `before`), then `const p = runPromise("ralph", { maxIterations: 1 })`, then **immediately** — synchronously, before any `await`, microtask yield, or other asynchronous interleaving on the test driver's side — snapshot the parent again the same way (call it `betweenSync`). Then `await p` and snapshot once more (`after`). Assert: (a) `betweenSync` set-equals `before` — `runPromise()` did **not** create a tmpdir synchronously before returning (an implementation that called `fs.mkdtempSync(...)` inside `runPromise()` itself, before returning the promise, would surface a new `loopx-*` entry here and fail), (b) the script observed a `LOOPX_TMPDIR` value during the run (recorded via the standard `observe-env` fixture) and that path's basename appears under the parent (the tmpdir was created asynchronously after `runPromise()` returned, between the `betweenSync` snapshot and promise settlement — proving the SPEC 9.2 "created asynchronously after return" clause), and (c) `after` does **not** contain the just-created `loopx-*` entry — SPEC 7.4 / 9.3 cleanup ran before `runPromise()` resolved. A buggy implementation that synchronously created the tmpdir inside `runPromise()` (e.g., to surface tmpdir-creation errors as a synchronous throw at the call site rather than as a promise rejection) would fail (a) and would also violate SPEC 9.3's "errors throw / reject" contract that all pre-iteration errors surface lazily as rejections. **Restore the original `TMPDIR` value in a `finally` block.** *(Spec 9.2, 7.4, 9.3)*
+- **T-TMP-26-temp**: `run()` programmatic snapshot-timing variant for `TEMP` (TMPDIR unset). Per SPEC 7.4 the tmpdir parent is `os.tmpdir()` evaluated in loopx's own `process.env`, captured on the same schedule as the inherited-env snapshot — lazy under `run()`. T-TMP-26 covers `TMPDIR`; this test parameterizes the lazy-snapshot timing axis over `TEMP`. **Pre-create both candidate parent directories** (`/tmp/loopx-temp-parent-A/` and `/tmp/loopx-temp-parent-B/`) before driving the test. Configure the driver process's inherited env with `TMPDIR` **unset**, `TMP` **unset**. Drive: `delete process.env.TMPDIR; delete process.env.TMP; process.env.TEMP = "/tmp/loopx-temp-parent-A"; const gen = run("ralph", { maxIterations: 1 }); process.env.TEMP = "/tmp/loopx-temp-parent-B"; await gen.next();` Apply the runtime-aware expected-parent logic from T-TMP-25a: assert `LOOPX_TMPDIR` lives under `/tmp/loopx-temp-parent-B` **iff** the active runtime's `os.tmpdir()` consults `TEMP` in this configuration; otherwise assert the parent matches `os.tmpdir()` evaluated in an identically-configured child process spawned with `TEMP=/tmp/loopx-temp-parent-B`. The mutation between `run()` returning and first `next()` redirects the parent on runtimes where `TEMP` is consulted — proving lazy-snapshot semantics for `TEMP` symmetrically with T-TMP-26 for `TMPDIR`. **Test must restore the original `TMPDIR` / `TEMP` / `TMP` values in a `finally` block.** *(Spec 7.4, 9.1)*
+- **T-TMP-26-tmp**: `run()` programmatic snapshot-timing variant for `TMP` (TMPDIR and TEMP unset). Same pattern as T-TMP-26-temp for the `TMP` branch. **Pre-create both candidate parent directories** (`/tmp/loopx-tmp-parent-A/` and `/tmp/loopx-tmp-parent-B/`). Configure the driver process's inherited env with `TMPDIR` **unset**, `TEMP` **unset**. Drive: `delete process.env.TMPDIR; delete process.env.TEMP; process.env.TMP = "/tmp/loopx-tmp-parent-A"; const gen = run("ralph", { maxIterations: 1 }); process.env.TMP = "/tmp/loopx-tmp-parent-B"; await gen.next();` Apply the runtime-aware expected-parent logic from T-TMP-25b: assert `LOOPX_TMPDIR` lives under `/tmp/loopx-tmp-parent-B` iff the active runtime's `os.tmpdir()` consults `TMP` in this configuration; otherwise anchor on `os.tmpdir()` evaluated in an identically-configured child process. Together with T-TMP-26 (`TMPDIR`) and T-TMP-26-temp (`TEMP`), this closes the lazy-snapshot timing × three-variable coverage on the `run()` surface. **Restore original env values in `finally`.** *(Spec 7.4, 9.1)*
+- **T-TMP-27-temp**: `runPromise()` programmatic snapshot-timing variant for `TEMP` (TMPDIR unset). Per SPEC 7.4 / 9.2 the tmpdir parent under `runPromise()` is captured eagerly at the call site. T-TMP-27 covers `TMPDIR`; this test parameterizes the eager-snapshot timing axis over `TEMP`. **Pre-create both candidate parent directories** (`/tmp/loopx-temp-parent-A/` and `/tmp/loopx-temp-parent-B/`) before invocation. Configure the driver process's inherited env with `TMPDIR` **unset**, `TMP` **unset**. Drive: `delete process.env.TMPDIR; delete process.env.TMP; process.env.TEMP = "/tmp/loopx-temp-parent-A"; const p = runPromise("ralph", { maxIterations: 1 }); process.env.TEMP = "/tmp/loopx-temp-parent-B"; await p;` Apply the runtime-aware expected-parent logic from T-TMP-25a: assert `LOOPX_TMPDIR` lives under `/tmp/loopx-temp-parent-A` iff the active runtime's `os.tmpdir()` consults `TEMP` in this configuration; otherwise assert the parent matches `os.tmpdir()` evaluated in an identically-configured child process spawned with `TEMP=/tmp/loopx-temp-parent-A` (the **pre-mutation** value). The mutation *after* `runPromise()` returned does not redirect the parent on runtimes where `TEMP` is consulted — proving eager-snapshot semantics for `TEMP` symmetrically with T-TMP-27 for `TMPDIR`. **Restore original env values in `finally`.** *(Spec 7.4, 9.2)*
+- **T-TMP-27-tmp**: `runPromise()` programmatic snapshot-timing variant for `TMP` (TMPDIR and TEMP unset). Same pattern as T-TMP-27-temp for the `TMP` branch. **Pre-create both candidate parent directories** (`/tmp/loopx-tmp-parent-A/` and `/tmp/loopx-tmp-parent-B/`). Configure inherited env with `TMPDIR` **unset**, `TEMP` **unset**. Drive: `delete process.env.TMPDIR; delete process.env.TEMP; process.env.TMP = "/tmp/loopx-tmp-parent-A"; const p = runPromise("ralph", { maxIterations: 1 }); process.env.TMP = "/tmp/loopx-tmp-parent-B"; await p;` Apply the runtime-aware expected-parent logic from T-TMP-25b: assert `LOOPX_TMPDIR` lives under `/tmp/loopx-tmp-parent-A` iff the active runtime's `os.tmpdir()` consults `TMP` in this configuration; otherwise anchor on `os.tmpdir()` evaluated in an identically-configured child process spawned with `TMP=/tmp/loopx-tmp-parent-A`. Together with T-TMP-27 (`TMPDIR`) and T-TMP-27-temp (`TEMP`), this closes the eager-snapshot timing × three-variable coverage on the `runPromise()` surface. **Restore original env values in `finally`.** *(Spec 7.4, 9.2)*
+- **T-TMP-28**: `TMPDIR` from a global env file does **not** redirect loopx's own tmpdir parent, but **does** reach the spawned script. Place `TMPDIR=/tmp/wrong-parent` in a global env file. Set the loopx inherited `TMPDIR=/tmp/right-parent`. Pre-create both `/tmp/wrong-parent` and `/tmp/right-parent` (at the test-isolated parent's level — see section 4.7's tmpdir test-parent isolation guidance) so the test does not rely on the literal `/tmp/...` paths existing. Fixture `.loopx/ralph/index.sh` observes both `LOOPX_TMPDIR` and `TMPDIR` via `observe-env` into separate marker files, then emits `stop:true`. Assert: (a) `LOOPX_TMPDIR` lives under `/tmp/right-parent` — loopx's own tmpdir-parent selection used the inherited `TMPDIR` snapshot from loopx's own `process.env`, not the global env-file value, per Spec 7.4 "`TMPDIR` / `TEMP` / `TMP` entries in env files or `RunOptions.env` reach spawned scripts but do not mutate loopx's own `process.env` and therefore do not redirect the tmpdir parent", and (b) the script's observed `TMPDIR` equals `/tmp/wrong-parent` — the global env-file value still reaches the spawned script's environment (per Spec 8.3 global-env-file injection tier), proving the global env-file entry is delivered as a regular environment variable to the child even though it does not redirect loopx's own tmpdir parent. T-TMP-29a covers the same two-pronged contract on the local (`-e`) env-file tier; T-TMP-28a / T-TMP-28b cover the same contract for `TEMP` / `TMP`. *(Spec 7.4, 8.3)*
+- **T-TMP-28a**: `TEMP` from a global env file does not redirect loopx's own tmpdir parent. SPEC 7.4 names `TMPDIR` / `TEMP` / `TMP` together as the variables `os.tmpdir()` reads; the "env files / `RunOptions.env` do not redirect tmpdir parent" rule applies symmetrically across all three. T-TMP-28 covers `TMPDIR` only; this test parameterizes the global env-file tier over `TEMP`. Same structure as T-TMP-28: place `TEMP=/tmp/wrong-parent` in a global env file; configure loopx's inherited environment with `TMPDIR` **unset**, `TMP` **unset**, and `TEMP=/tmp/right-parent`; pre-create both directories. Run `loopx run -n 1 ralph` against a fixture that observes `LOOPX_TMPDIR` and `TEMP`. Apply runtime-aware expected-parent logic from T-TMP-25a: assert `LOOPX_TMPDIR` lives under `/tmp/right-parent` **iff** the active runtime's `os.tmpdir()` consults `TEMP` in this configuration; otherwise assert `LOOPX_TMPDIR`'s parent matches `os.tmpdir()` evaluated in an identically-configured child Node/Bun process spawned with the same inherited environment (this anchors the assertion on loopx's `os.tmpdir()` call rather than on a hard-coded `TEMP` semantic, keeping the test honest across runtimes). Always assert (b): the child's observed `TEMP` equals `/tmp/wrong-parent` — the global env-file value reaches the spawned script's environment regardless of whether loopx's own tmpdir-parent selection consulted it. A buggy implementation that mutated loopx's own `process.env` from the global env file would redirect `os.tmpdir()` to `/tmp/wrong-parent` and fail (a) under any runtime that consults `TEMP`. *(Spec 7.4, 8.3)*
+- **T-TMP-28b**: `TMP` from a global env file does not redirect loopx's own tmpdir parent. Same pattern as T-TMP-28a for the `TMP` branch: configure loopx's inherited env with `TMPDIR` **unset**, `TEMP` **unset**, `TMP=/tmp/right-parent`, and a global env file containing `TMP=/tmp/wrong-parent`; pre-create both directories. Run loopx and observe `LOOPX_TMPDIR` and `TMP`. Apply the same runtime-aware expected-parent logic (T-TMP-25b): assert `LOOPX_TMPDIR` lives under `/tmp/right-parent` iff the active runtime's `os.tmpdir()` consults `TMP` in this configuration; otherwise anchor on `os.tmpdir()` evaluated in an identically-configured child process. Always assert the child's observed `TMP` equals `/tmp/wrong-parent`. Together with T-TMP-28 (`TMPDIR`) and T-TMP-28a (`TEMP`), this closes the global env-file tier × three-variable coverage for the SPEC 7.4 "env files do not redirect tmpdir parent" rule. *(Spec 7.4, 8.3)*
+- **T-TMP-29**: `TMPDIR` from `RunOptions.env` does **not** redirect loopx's own tmpdir parent. **Pre-create `/tmp/right-parent/`** (the inherited-env value, which is the parent loopx's own `os.tmpdir()` selects) before invocation; the wrong-parent value need not exist on disk because loopx must not consult it. Set loopx inherited `TMPDIR=/tmp/right-parent`. Call `runPromise("ralph", { env: { TMPDIR: "/tmp/wrong-parent" } })`. Script observes `LOOPX_TMPDIR`. Assert tmpdir lives under `/tmp/right-parent`. `RunOptions.env` merges into the child environment; it does not mutate loopx's own `process.env`. T-TMP-29b / T-TMP-29c cover the same contract for `TEMP` / `TMP`. *(Spec 7.4, 9.5)*
+- **T-TMP-29b**: `TEMP` from `RunOptions.env` does not redirect loopx's own tmpdir parent. SPEC 7.4 / 9.5 apply the env-files-and-`RunOptions.env`-do-not-redirect-tmpdir rule symmetrically across `TMPDIR` / `TEMP` / `TMP`. T-TMP-29 covers `TMPDIR`; this test parameterizes `RunOptions.env` over `TEMP`. **Pre-create `/tmp/right-parent/`** before invocation. Configure the driver process's inherited env with `TMPDIR` **unset**, `TMP` **unset**, `TEMP=/tmp/right-parent`. Call `runPromise("ralph", { env: { TEMP: "/tmp/wrong-parent" } })`. Script observes `LOOPX_TMPDIR` and `TEMP` via `observe-env`. Apply the runtime-aware expected-parent logic from T-TMP-25a: assert `LOOPX_TMPDIR` lives under `/tmp/right-parent` iff the active runtime's `os.tmpdir()` consults `TEMP` in this configuration; otherwise assert the parent matches `os.tmpdir()` evaluated in an identically-configured child process. Always assert the child's observed `TEMP` equals `/tmp/wrong-parent` (the `RunOptions.env` value reached the spawned script's environment per the SPEC 8.3 `RunOptions.env` tier). *(Spec 7.4, 9.5, 8.3)*
+- **T-TMP-29c**: `TMP` from `RunOptions.env` does not redirect loopx's own tmpdir parent. Same pattern as T-TMP-29b for the `TMP` branch: **pre-create `/tmp/right-parent/`** before invocation; configure inherited env with `TMPDIR` **unset**, `TEMP` **unset**, `TMP=/tmp/right-parent`; call `runPromise("ralph", { env: { TMP: "/tmp/wrong-parent" } })`. Apply the same runtime-aware expected-parent logic (T-TMP-25b). Always assert the child's observed `TMP` equals `/tmp/wrong-parent`. Together with T-TMP-29 (`TMPDIR`) and T-TMP-29b (`TEMP`), this closes the `RunOptions.env` tier × three-variable coverage. *(Spec 7.4, 9.5, 8.3)*
+- **T-TMP-29a**: `TMPDIR` from a local (`-e`) env file does **not** redirect loopx's own tmpdir parent. **Pre-create `/tmp/right-parent/`** before invocation. Set loopx inherited `TMPDIR=/tmp/right-parent`. Create a local env file via `writeEnvFileRaw` containing `TMPDIR=/tmp/wrong-parent`. Fixture `.loopx/ralph/index.sh` observes both `LOOPX_TMPDIR` and `TMPDIR` via `observe-env`, performs an in-script `stat` of the observed `$LOOPX_TMPDIR` path (during execution, recording "exists as a directory" to a marker), then emits `stop:true`. Run `loopx run -e <envfile> -n 1 ralph`. Assert: (a) the child's observed `TMPDIR` equals `/tmp/wrong-parent` (local env-file tier injected the override into the spawned script's environment per Spec 8.3), (b) `LOOPX_TMPDIR` lives under `/tmp/right-parent` (loopx's own tmpdir-parent selection used the inherited `TMPDIR` snapshot from loopx's own `process.env`, not the local env-file value — per Spec 7.4 "`TMPDIR` / `TEMP` / `TMP` entries in env files or `RunOptions.env` reach spawned scripts but do not mutate loopx's own `process.env` and therefore do not redirect the tmpdir parent"), and (c) the during-run stat marker records "exists as a directory". T-TMP-28 covers the global env-file tier and T-TMP-29 covers `RunOptions.env`; this test closes the local `-e` tier for `TMPDIR`. T-TMP-29d / T-TMP-29e parameterize the local `-e` tier over `TEMP` / `TMP`. *(Spec 7.4, 8.2, 8.3)*
+- **T-TMP-29d**: `TEMP` from a local (`-e`) env file does not redirect loopx's own tmpdir parent. Local `-e` tier counterpart to T-TMP-28a (global env file) and T-TMP-29b (`RunOptions.env`). **Pre-create `/tmp/right-parent/`** before invocation. Configure loopx's inherited env with `TMPDIR` **unset**, `TMP` **unset**, `TEMP=/tmp/right-parent`. Create a local env file via `writeEnvFileRaw` containing `TEMP=/tmp/wrong-parent`. Fixture observes `LOOPX_TMPDIR` and `TEMP`. Run `loopx run -e <envfile> -n 1 ralph`. Apply the runtime-aware expected-parent logic from T-TMP-25a (anchor on `os.tmpdir()` evaluated in an identically-configured child process when the active runtime does not consult `TEMP`). Always assert the child's observed `TEMP` equals `/tmp/wrong-parent`. *(Spec 7.4, 8.2, 8.3)*
+- **T-TMP-29e**: `TMP` from a local (`-e`) env file does not redirect loopx's own tmpdir parent. Same pattern as T-TMP-29d for the `TMP` branch: **pre-create `/tmp/right-parent/`** before invocation; inherited env with `TMPDIR` **unset**, `TEMP` **unset**, `TMP=/tmp/right-parent`; local env file `TMP=/tmp/wrong-parent`. Apply the runtime-aware expected-parent logic (T-TMP-25b). Always assert the child's observed `TMP` equals `/tmp/wrong-parent`. Together with T-TMP-28a/28b, T-TMP-29b/29c, and T-TMP-29d, this closes the SPEC 7.4 "env files / `RunOptions.env` do not redirect tmpdir parent" rule across the **CLI**-driven injection tiers and all three variables (`TMPDIR`, `TEMP`, `TMP`). T-TMP-29f / T-TMP-29g / T-TMP-29h close the equivalent rule for the **programmatic `runPromise({ envFile })`** surface. *(Spec 7.4, 8.2, 8.3)*
+- **T-TMP-29f**: `TMPDIR` from a programmatic local env file (`runPromise({ envFile })`) does **not** redirect loopx's own tmpdir parent. Programmatic counterpart to T-TMP-29a (CLI `-e`). T-TMP-29 covers `RunOptions.env`, T-TMP-28 / 28a / 28b cover the global env-file tier, and T-TMP-29a / 29d / 29e cover the CLI `-e` tier; this test fills the programmatic `RunOptions.envFile` tier — distinct from `RunOptions.env` because env files are loaded by reading the file at the resolved path during pre-iteration, while `RunOptions.env` is captured as a shallow copy at the call site. A buggy implementation that funneled local env-file values into loopx's own `process.env` (or otherwise allowed file-loaded `TMPDIR` entries to redirect the tmpdir parent) when the file was supplied programmatically — but not when supplied via CLI `-e` — would pass T-TMP-29a but fail this test. **Pre-create `/tmp/right-parent/`** before invocation. Configure loopx's inherited `TMPDIR=/tmp/right-parent`. Create a local env file via `writeEnvFileRaw` containing `TMPDIR=/tmp/wrong-parent`. Fixture `.loopx/ralph/index.sh` observes both `LOOPX_TMPDIR` and `TMPDIR` via `observe-env`, then emits `stop:true`. Call `runPromise("ralph", { envFile: "<envfile-path>", maxIterations: 1 })`. Assert: (a) the child's observed `TMPDIR` equals `/tmp/wrong-parent` (programmatic local env-file tier injected the override into the spawned script's environment per Spec 8.3 tier 3), and (b) `LOOPX_TMPDIR` lives under `/tmp/right-parent` (loopx's own tmpdir-parent selection used the inherited `TMPDIR` snapshot, not the local env-file value, per Spec 7.4). *(Spec 7.4, 8.2, 8.3, 9.5)*
+- **T-TMP-29g**: `TEMP` from a programmatic local env file (`runPromise({ envFile })`) does not redirect loopx's own tmpdir parent. Programmatic counterpart to T-TMP-29d (CLI `-e` × `TEMP`). **Pre-create `/tmp/right-parent/`** before invocation. Configure loopx's inherited env with `TMPDIR` **unset**, `TMP` **unset**, `TEMP=/tmp/right-parent`. Create a local env file containing `TEMP=/tmp/wrong-parent`. Fixture observes `LOOPX_TMPDIR` and `TEMP`. Call `runPromise("ralph", { envFile: "<envfile-path>", maxIterations: 1 })`. Apply the runtime-aware expected-parent logic from T-TMP-25a (anchor on `os.tmpdir()` evaluated in an identically-configured child process when the active runtime does not consult `TEMP`). Always assert the child's observed `TEMP` equals `/tmp/wrong-parent`. *(Spec 7.4, 8.2, 8.3, 9.5)*
+- **T-TMP-29h**: `TMP` from a programmatic local env file (`runPromise({ envFile })`) does not redirect loopx's own tmpdir parent. Programmatic counterpart to T-TMP-29e (CLI `-e` × `TMP`). **Pre-create `/tmp/right-parent/`** before invocation. Inherited env with `TMPDIR` **unset**, `TEMP` **unset**, `TMP=/tmp/right-parent`; local env file `TMP=/tmp/wrong-parent`. Call `runPromise("ralph", { envFile: "<envfile-path>", maxIterations: 1 })`. Apply the runtime-aware expected-parent logic (T-TMP-25b). Always assert the child's observed `TMP` equals `/tmp/wrong-parent`. Together with T-TMP-29f and T-TMP-29g, this closes the programmatic `RunOptions.envFile` × `runPromise()` × three-variable coverage. T-TMP-29i / T-TMP-29j / T-TMP-29k extend the same contract to the `run()` generator surface. *(Spec 7.4, 8.2, 8.3, 9.5)*
+- **T-TMP-29i**: `TMPDIR` from a programmatic local env file on the `run()` **generator surface** (`run("ralph", { envFile, maxIterations: 1 })`) does **not** redirect loopx's own tmpdir parent. `run()` counterpart to T-TMP-29f (which exercises the same contract on `runPromise()`). Although both `run()` and `runPromise()` share the SPEC 9.1 / 9.2 lazy-vs-eager option-snapshot timing distinction, the env-file loading step itself runs inside the same pre-iteration sequence on both surfaces — but `run()` defers it to first `next()` while `runPromise()` runs it as part of the eager pre-iteration pipeline. A buggy implementation that (a) loaded the env file into loopx's own `process.env` only on the lazy `run()` first-`next()` path (e.g., to "refresh" the parent at first `next()` after the lazy snapshot) but not on the eager `runPromise()` path, or (b) routed the file-loaded values into the tmpdir-parent selection only on the `run()` generator surface, would pass T-TMP-29f but fail this test. **Pre-create `/tmp/right-parent/`** before invocation. Configure loopx's inherited `TMPDIR=/tmp/right-parent`. Create a local env file via `writeEnvFileRaw` containing `TMPDIR=/tmp/wrong-parent`. Fixture `.loopx/ralph/index.sh` observes both `LOOPX_TMPDIR` and `TMPDIR` via `observe-env`, then emits `stop:true`. Drive: `const gen = run("ralph", { envFile: "<envfile-path>", maxIterations: 1 }); for await (const out of gen) { /* drain */ }` (or equivalent — full settlement is required so cleanup runs and the marker reads can complete deterministically). Assert: (a) the child's observed `TMPDIR` equals `/tmp/wrong-parent` (the local env-file value reaches the spawned script's environment per Spec 8.3 tier 3 on the `run()` generator surface, identical to `runPromise()` per Spec 9.1 / 9.2 / 8.3 — `run()` does not skip env-file loading just because option capture is lazy), and (b) `LOOPX_TMPDIR` lives under `/tmp/right-parent` (loopx's own tmpdir-parent selection used the inherited `TMPDIR` snapshot captured at first `next()` per SPEC 7.4's lazy-snapshot rule for `run()`, not the local env-file value, per Spec 7.4 "`TMPDIR` / `TEMP` / `TMP` entries in env files or `RunOptions.env` reach spawned scripts but do not mutate loopx's own `process.env` and therefore do not redirect the tmpdir parent"). *(Spec 7.4, 8.2, 8.3, 9.1, 9.5)*
+- **T-TMP-29j**: `TEMP` from a programmatic local env file on the `run()` **generator surface** does not redirect loopx's own tmpdir parent. `run()` counterpart to T-TMP-29g (`runPromise()` × `TEMP`). **Pre-create `/tmp/right-parent/`** before invocation. Configure loopx's inherited env with `TMPDIR` **unset**, `TMP` **unset**, `TEMP=/tmp/right-parent`. Create a local env file containing `TEMP=/tmp/wrong-parent`. Fixture observes `LOOPX_TMPDIR` and `TEMP`. Drive: `const gen = run("ralph", { envFile: "<envfile-path>", maxIterations: 1 }); for await (const out of gen) { /* drain */ }`. Apply the runtime-aware expected-parent logic from T-TMP-25a (anchor on `os.tmpdir()` evaluated in an identically-configured child process when the active runtime does not consult `TEMP`). Always assert the child's observed `TEMP` equals `/tmp/wrong-parent`. *(Spec 7.4, 8.2, 8.3, 9.1, 9.5)*
+- **T-TMP-29k**: `TMP` from a programmatic local env file on the `run()` **generator surface** does not redirect loopx's own tmpdir parent. `run()` counterpart to T-TMP-29h (`runPromise()` × `TMP`). **Pre-create `/tmp/right-parent/`** before invocation. Inherited env with `TMPDIR` **unset**, `TEMP` **unset**, `TMP=/tmp/right-parent`; local env file `TMP=/tmp/wrong-parent`. Drive: `const gen = run("ralph", { envFile: "<envfile-path>", maxIterations: 1 }); for await (const out of gen) { /* drain */ }`. Apply the runtime-aware expected-parent logic (T-TMP-25b). Always assert the child's observed `TMP` equals `/tmp/wrong-parent`. Together with T-TMP-29i and T-TMP-29j, this closes the programmatic `RunOptions.envFile` × `run()` × three-variable coverage on the generator surface, completing the SPEC 7.4 "env files / `RunOptions.env` do not redirect tmpdir parent" rule across **all four injection tiers** (global env file, CLI `-e`, programmatic `RunOptions.envFile` on both `runPromise()` and `run()`, `RunOptions.env`) × **both programmatic surfaces** (`runPromise()` via T-TMP-29f / T-TMP-29g / T-TMP-29h, `run()` via T-TMP-29i / T-TMP-29j / T-TMP-29k) × **all three variables**. *(Spec 7.4, 8.2, 8.3, 9.1, 9.5)*
+
+##### Cleanup Safety (Identity-Fingerprint, Symlink / Non-Directory / Mismatched Directory)
+
+SPEC 7.4 "Identity-fingerprint cleanup safety" defines normative rules for cleanup dispatch: symlinks are unlinked without following, regular files and mismatched directories are left with a warning, and nested symlink entries are unlinked but not traversed. SPEC 7.4 also specifies that **loopx does not reap stale tmpdirs at startup** and **does not chase renamed-away tmpdirs**. These rules are black-box testable and must be covered.
+
+All tests in this block use a fixture that observes `LOOPX_TMPDIR` into a marker, then performs the relevant filesystem manipulation on the reported path (rename, replacement with symlink, replacement with regular file, or nested symlink creation) before loopx exits. Tests inspect the filesystem after loopx exits to verify the safety rules held.
+
+- **T-TMP-32**: No stale-tmpdir reaping at startup. Before running loopx, pre-create a directory matching the `loopx-*` naming pattern under the test-isolated tmpdir parent selected via `TMPDIR` (per the section 4.7 tmpdir-block preface guidance: set `TMPDIR` to a per-test isolated parent directory, then create `<TMPDIR>/loopx-stale-xyz/` with a marker file inside). Run `loopx run -n 1 ralph` against a normal fixture, with the same `TMPDIR` configured in loopx's inherited environment so loopx's own tmpdir creation also lives under that parent. After loopx exits 0, assert: (a) the pre-created `loopx-stale-xyz/` directory still exists with its marker file intact, and (b) loopx's own freshly-created `loopx-*` directory (observed via `observe-env` on `LOOPX_TMPDIR`) has been cleaned up. Per SPEC 7.4 "loopx does not reap stale tmpdirs at startup". The test-isolated parent (rather than the shared `os.tmpdir()` default) is required by the suite-wide flakiness-guidance preface — concurrent test workers under `/tmp` would race against this test's stale-entry observation. *(Spec 7.4)*
+- **T-TMP-33**: Renamed-away tmpdir is not chased, and no cleanup warning is emitted for the resulting ENOENT at the original path. Fixture observes `LOOPX_TMPDIR`, writes a marker `initialized` into it, then renames the tmpdir directory itself (e.g., `mv "$LOOPX_TMPDIR" "$LOOPX_TMPDIR-renamed"` — performed before the script exits), then emits `stop:true`. After loopx exits 0, assert: (a) the original tmpdir path (which is now gone due to the rename) does not exist, (b) the renamed path (`-renamed` suffix) **still exists** with the `initialized` marker intact — loopx did not chase the renamed directory and did not remove it, and (c) stderr contains **no cleanup-related warning** for the ENOENT at the original path — per SPEC 7.4's "If `$LOOPX_TMPDIR` no longer exists at cleanup time, cleanup is a no-op", a missing tmpdir at cleanup time is the expected condition when the script renamed it away, not a warning-worthy anomaly. T-TMP-35 / T-TMP-36 pin down that mismatched-directory and regular-file replacements do emit exactly one warning; this test pins down the symmetric rule that ENOENT-at-cleanup is silent (no warning emitted), so that warning cardinality across the cleanup-dispatch tree is fully characterized. Per SPEC 7.4 "A script that removes or renames its tmpdir during the run defeats automatic cleanup of the moved directory; loopx does not chase renamed tmpdirs." *(Spec 7.4)*
+- **T-TMP-34**: Cleanup of a symlink replacement removes the symlink entry only, not the target, and emits **no** cleanup warning. Fixture observes `LOOPX_TMPDIR`, writes a marker `target-marker` inside an external directory (e.g., `$LOOPX_PROJECT_ROOT/target-survives/target-marker`), then `rm -rf "$LOOPX_TMPDIR"` and `ln -s "$LOOPX_PROJECT_ROOT/target-survives" "$LOOPX_TMPDIR"`, then emits `stop:true`. After loopx exits 0, assert: (a) the `$LOOPX_TMPDIR` path no longer exists (loopx unlinked the symlink entry), (b) the external `target-survives/` directory still exists with `target-marker` intact (loopx did not follow the symlink target), and (c) **stderr contains no cleanup-related warning** — SPEC 7.4 enumerates warning emission only on cleanup-failure (lstat fails, unlink fails, recursive removal fails) or non-directory non-symlink at path (rule 3) or mismatched directory (rule 5); the symlink branch (rule 2) is a successful unlink and produces no warning. T-TMP-35 / T-TMP-36 pin down that rules 3 and 5 do emit exactly one warning, and T-TMP-33 pins down that the ENOENT branch (rule 1) emits no warning; this assertion closes the same warning-cardinality contract for the symlink-success branch, distinguishing "symlink unlinked successfully" from "symlink unlink failed" (which would emit a single warning per the cleanup-failure clause). The cleanup-warning text format is implementation-defined per SPEC 7.4 warning-text-broadness convention; the assertion here is **negative** (no cleanup-related warning emitted at all on stderr), not text-pattern-specific. Per SPEC 7.4 cleanup-safety rule 2: "Path is a symlink: unlink the symlink entry; do not follow the target." *(Spec 7.4)*
+- **T-TMP-35**: Cleanup leaves a regular-file replacement in place with a warning. Fixture observes `LOOPX_TMPDIR`, then `rm -rf "$LOOPX_TMPDIR"` and `printf '%s' "regular-file-replacement" > "$LOOPX_TMPDIR"` (tmpdir path is now a regular file), then emits `stop:true`. After loopx exits 0, assert: (a) the `$LOOPX_TMPDIR` path still exists and is a regular file with content `regular-file-replacement` (the filesystem-safety outcome per SPEC 7.4 rule 3: the regular file was not unlinked), (b) stderr contains exactly one cleanup-related warning (per-run cleanup-warning cardinality), and (c) the CLI exit code is 0 (the cleanup warning does not affect the exit code). The warning text is implementation-defined per SPEC 7.4; do **not** require it to mention the path, the type, or any specific phrasing — only that a single cleanup-related warning is emitted. Per SPEC 7.4 cleanup-safety rule 3: "Path is a regular file ... : leave in place with a stderr warning." *(Spec 7.4)*
+- **T-TMP-35a**: `runPromise()` outcome is unaffected by a cleanup warning (regular-file replacement). Programmatic-API counterpart to T-TMP-35. SPEC 7.4: "cleanup warnings do not affect the CLI exit code, the generator outcome, or the promise rejection reason." T-TMP-35 covers the CLI exit-code clause; this test pins down the promise-outcome clause. Use the same fixture (script observes `LOOPX_TMPDIR`, replaces it with a regular file, emits `stop: true`). Call `runPromise("ralph", { maxIterations: 1 })`. Capture the driver-process stderr for the duration of the promise. Assert: (a) the promise **resolves** (does not reject) — the cleanup warning did not promote to a rejection, (b) the resolved array's single `Output` has `stop: true` (the terminal outcome is what the script produced, not what cleanup observed), (c) the captured stderr contains exactly one cleanup-related warning, and (d) the `$LOOPX_TMPDIR` path still exists as a regular file (the filesystem-safety rule held). *(Spec 7.4, 9.2)*
+- **T-TMP-35b**: `run()` generator outcome is unaffected by a cleanup warning (regular-file replacement). The generator surface counterpart to T-TMP-35a. Same fixture; drive via `const gen = run("ralph", { maxIterations: 1 }); const first = await gen.next(); const second = await gen.next();`. Assert: (a) `first.done === false` and `first.value.stop === true` (the final output was yielded), (b) `second.done === true` and no error was thrown (the generator settled cleanly — the cleanup warning did not promote to a `throw`), (c) stderr contains exactly one cleanup-related warning, and (d) the `$LOOPX_TMPDIR` path still exists as a regular file. Together with T-TMP-35 (CLI) and T-TMP-35a (`runPromise`), this closes the cleanup-warning-does-not-affect-outcome coverage across all three surfaces for the regular-file-replacement branch. *(Spec 7.4, 9.1)*
+- **T-TMP-35c**: Cleanup warning does not mask a script-error exit code, and the surfaced failure is observably the **script failure**, not the cleanup warning. SPEC 7.4 says "cleanup warnings do not affect the CLI exit code, the generator outcome, or the promise rejection reason." T-TMP-35 / T-TMP-35a / T-TMP-35b all use successful (`stop: true`) script termination — the cleanup warning is cardinality-tested against a successful run. This test pins down the error-path variant: a cleanup warning must not promote a `1`-exit-from-the-script into a cleanup-failure exit, nor hide it as `0`, and the error output must identify the script failure as the primary failure cause rather than conflating it with the cleanup-warning category. **Because both the script-failure path and a hypothetical cleanup-promoted-to-failure path would produce exit code `1` on the CLI**, the test cannot distinguish them by exit code alone — it must additionally assert the **presence of a script-failure marker on stderr that is observably disjoint from the cleanup warning**. Fixture `.loopx/ralph/index.sh` observes `LOOPX_TMPDIR`, writes a **distinctive script-failure marker line** to stderr before any tmpdir tampering (e.g., `printf 'SCRIPT-FAILURE-MARKER-T-TMP-35C: script about to fail with non-zero exit\n' >&2`), then `rm -rf "$LOOPX_TMPDIR"` and `printf '%s' "regular-file-replacement" > "$LOOPX_TMPDIR"` (tmpdir path is now a regular file — the cleanup-safety rule 3 path), then `exit 1` (script itself fails). Run CLI. Assert: (a) exit code 1 — from the **script failure**, not the cleanup warning. An implementation that masked the script failure as exit 0 (because cleanup produced "only a warning") would fail this assertion. (b) stderr contains the distinctive `SCRIPT-FAILURE-MARKER-T-TMP-35C` line (the script's own pre-failure output reached stderr), (c) stderr contains exactly one cleanup-related warning, (d) the cleanup-related warning and the script-failure marker are **distinct stderr lines** (they do not overlap in content), proving that the cleanup warning did not replace, wrap, or suppress the script-failure output, and (e) the `$LOOPX_TMPDIR` path still exists and is a regular file (SPEC 7.4 rule 3: regular-file replacement is left in place). Together, (a)+(b)+(d) rule out the "cleanup warning masks the script failure" failure mode: the test harness can see the script-originated stderr alongside the cleanup warning, on its own line, so the script failure remains the primary observable failure cause even when cleanup also emits a warning. Parameterize the test over regular-file and mismatched-directory replacement variants (the two warning-emitting branches with a surviving post-cleanup path), using the T-TMP-36-style rename-aside pattern for the mismatched-directory case to guarantee inode-distinctness. This is the CLI-side pinning of the "cleanup warning does not affect outcome" clause under a failing terminal; the `runPromise()` / `run()` counterparts are covered by T-TMP-35d / T-TMP-35e (below) under the same error-terminal. *(Spec 7.4, 12)*
+- **T-TMP-35d**: `runPromise()` cleanup warning does not mask a script-error rejection reason. Programmatic-API counterpart to T-TMP-35c. SPEC 7.4 says "cleanup warnings do not affect ... the promise rejection reason." T-TMP-35a / T-TMP-36a cover the success-terminal (resolve) branch — the cleanup warning does not promote a `stop: true` resolution to a rejection. This test covers the **error-terminal (reject) branch**: a script that exits non-zero and also triggers a cleanup-safety rule must reject with the **script failure** as the rejection reason, not a cleanup-failure error. **Parameterize the test over the two warning-emitting cleanup-safety branches with a surviving post-cleanup path** — matching T-TMP-35c on the CLI surface so the programmatic-counterpart coverage spans the same pair of branches: **(variant a) regular-file replacement** — `rm -rf "$LOOPX_TMPDIR"` and `printf '%s' "regular-file-replacement" > "$LOOPX_TMPDIR"` (SPEC 7.4 cleanup-safety rule 3 path); **(variant b) mismatched-directory replacement** — `mv "$LOOPX_TMPDIR" "$LOOPX_TMPDIR-original-aside" && mkdir "$LOOPX_TMPDIR" && touch "$LOOPX_TMPDIR/mismatched-marker"` using the T-TMP-36-style rename-aside pattern to guarantee inode-distinctness (SPEC 7.4 cleanup-safety rule 5 path). For each variant, the fixture `.loopx/ralph/index.sh` observes `LOOPX_TMPDIR`, performs the variant-specific replacement, then `exit 1` (script fails). Call `runPromise("ralph", { maxIterations: 1 })` per variant. Capture driver-process stderr for the duration of the promise. Assert (per variant): (a) the promise **rejects** (does not resolve), (b) the rejection reason is a **script-failure error** (matching the same shape as T-API-15 / T-API-19's script-non-zero-exit rejections — exact error class implementation-defined, but it must reference the script failure / non-zero exit, not a cleanup-failure / cleanup-safety-rule classification), (c) the captured stderr contains exactly one cleanup-related warning, and (d) for variant (a) the `$LOOPX_TMPDIR` path still exists as a regular file with content `regular-file-replacement` (SPEC 7.4 rule 3); for variant (b) the `$LOOPX_TMPDIR` path still exists as a directory with the `mismatched-marker` file inside (SPEC 7.4 rule 5). A buggy implementation that promoted the cleanup warning to the rejection reason — wrapping the script-failure error or replacing it with a cleanup-related error — would fail (b) on either variant; an implementation that masked the script failure entirely (resolving with the partial output array because cleanup produced "only a warning") would fail (a). *(Spec 7.4, 9.2, 12)*
+- **T-TMP-35e**: `run()` generator cleanup warning does not mask a script-error throw. Generator-surface counterpart to T-TMP-35d. SPEC 7.4 says "cleanup warnings do not affect ... the generator outcome." T-TMP-35b / T-TMP-36b cover the success-terminal (clean settlement) branch. This test covers the **error-terminal (throw) branch**: when a script exits non-zero and also triggers a cleanup-safety rule, the generator must throw the **script-failure error**, not a cleanup-failure error. **Parameterize over the same two warning-emitting cleanup-safety branches as T-TMP-35d** — **(variant a) regular-file replacement** (rule 3) and **(variant b) mismatched-directory replacement** using the T-TMP-36-style rename-aside pattern (rule 5) — so the programmatic-counterpart coverage spans the same pair of branches T-TMP-35c covers on the CLI surface. For each variant, drive: `const gen = run("ralph", { maxIterations: 1 }); let thrown; try { for await (const _ of gen) { /* consume yields if any */ } } catch (e) { thrown = e; }`. Assert (per variant): (a) the generator threw (the `for await` exited via a rejection rather than completing cleanly), (b) the thrown error is a **script-failure error** (same error-shape contract as T-TMP-35d, applied to the generator surface), (c) stderr contains exactly one cleanup-related warning, and (d) for variant (a) the `$LOOPX_TMPDIR` path still exists as a regular file; for variant (b) the path still exists as a directory with the `mismatched-marker` file inside. Together with T-TMP-35c (CLI) and T-TMP-35d (`runPromise`), this closes the cleanup-warning-does-not-mask-error-path coverage across all three surfaces × both warning-emitting cleanup-safety branches, matching the pattern T-TMP-35 / T-TMP-35a / T-TMP-35b / T-TMP-36 / T-TMP-36a / T-TMP-36b establishes for the success-path. *(Spec 7.4, 9.1, 12)*
+- **T-TMP-35f**: CLI signal cleanup warning does not mask the signal exit code. SPEC 7.4 says "cleanup warnings do not affect the CLI exit code, the generator outcome, or the promise rejection reason." T-TMP-35 covers the **success-terminal (stop: true)** branch on the CLI; T-TMP-35c covers the **script-error-terminal** branch on the CLI. Neither covers the **signal-terminal** branch — a script that triggers a cleanup-safety rule and then is interrupted by SIGINT / SIGTERM. The signal-terminal case exercises a structurally distinct code path: the cleanup warning must not mask the `128 + signal number` exit code that SPEC 7.3 / 7.4 require for signal-driven termination, and must not be promoted to a cleanup-failure-class exit. **Parameterize over both signals (SIGINT and SIGTERM) and both warning-emitting cleanup-safety branches** (regular-file replacement per rule 3; mismatched-directory replacement per rule 5 via the T-TMP-36-style rename-aside pattern). Fixture `.loopx/ralph/index.sh` observes `LOOPX_TMPDIR` into a marker (path external to the tmpdir so it survives cleanup), performs the variant-specific replacement (variant a: `rm -rf "$LOOPX_TMPDIR"` then `printf '%s' "regular-file-replacement" > "$LOOPX_TMPDIR"`; variant b: `mv "$LOOPX_TMPDIR" "$LOOPX_TMPDIR-original-aside" && mkdir "$LOOPX_TMPDIR" && touch "$LOOPX_TMPDIR/mismatched-marker"`), writes `"ready"` to stderr, then blocks indefinitely (`while true; do sleep 1; done`). Run via `runCLIWithSignal`. Wait for `"ready"` on stderr, then send the variant-specific signal (SIGINT or SIGTERM) to loopx. Assert per variant (signal × cleanup-safety branch — four sub-cases total): (a) loopx exits with the **signal exit code** — `130` for SIGINT, `143` for SIGTERM (the cleanup warning did not mask, replace, or override the signal exit code), (b) stderr contains exactly one cleanup-related warning (per-run cleanup-warning cardinality from SPEC 7.4 — the signal terminal does not double the warning emission), and (c) for the regular-file-replacement variant the `$LOOPX_TMPDIR` path still exists as a regular file with content `regular-file-replacement` (cleanup-safety rule 3 held under the signal terminal); for the mismatched-directory variant the path still exists as a directory with the `mismatched-marker` file inside (rule 5 held). Together with T-TMP-35 (success terminal, CLI) and T-TMP-35c (script-error terminal, CLI), this closes the CLI-surface "cleanup warning does not affect outcome" coverage across all three terminal types — success / script-error / signal — × both warning-emitting cleanup-safety branches. A buggy implementation that promoted the cleanup warning to a cleanup-failure-class exit code under the signal terminal (e.g., exit `1` instead of the signal code, or some implementation-specific cleanup-failure code) would fail (a). *(Spec 7.4, 7.3, 12)*
+- **T-TMP-35g**: `runPromise()` abort cleanup warning does not mask the abort rejection reason. Programmatic-API counterpart to T-TMP-35f for the abort terminal. SPEC 7.4 says "cleanup warnings do not affect ... the promise rejection reason." T-TMP-35a covers the success terminal and T-TMP-35d covers the script-error terminal on the `runPromise()` surface; this test pins down the **abort terminal**. Same parameterization as T-TMP-35f over both warning-emitting cleanup-safety branches (regular-file replacement and mismatched-directory replacement via the T-TMP-36-style rename-aside pattern). Fixture observes `LOOPX_TMPDIR` into a marker, writes its PID to a separate marker, performs the variant-specific replacement, writes `"ready"` to stderr, then blocks indefinitely. Use `runAPIDriverLive()` to obtain a driver-process handle. Drive: `const c = new AbortController(); const promise = runPromise("ralph", { signal: c.signal });` `await waitForStderr("ready")` on the driver stream. Capture driver-process stderr for the duration of the promise. Call `c.abort()` from the harness via the driver-handle coordination mechanism (mirroring T-API-10d-promise's coordination pattern). `await expect(promise).rejects.toThrow(<abort error>)`. Assert per variant: (a) the promise **rejects** with the **abort** error (matching T-API-10d-promise / T-API-10e-promise's abort-error contract — the cleanup warning did not promote to a cleanup-failure-class rejection nor replace the abort error), (b) the captured stderr contains exactly one cleanup-related warning, and (c) for the regular-file-replacement variant the `$LOOPX_TMPDIR` path still exists as a regular file (rule 3 held under abort); for the mismatched-directory variant the path still exists as a directory with the `mismatched-marker` file inside (rule 5 held). The active child must also be terminated (the script's PID from the marker is no longer running) — matching the abort-driven process-group-termination contract from T-API-10d. A buggy implementation that wrapped the abort error in a cleanup-failure error (or surfaced a cleanup-failure error in place of the abort error) would fail (a). *(Spec 7.4, 9.2, 9.1, 12)*
+- **T-TMP-35h**: `run()` generator abort cleanup warning does not mask the abort throw. Generator-surface counterpart to T-TMP-35g. SPEC 7.4 says "cleanup warnings do not affect ... the generator outcome." T-TMP-35b covers the success terminal and T-TMP-35e covers the script-error terminal on the `run()` surface; this test pins down the **abort terminal**. Same fixture and parameterization as T-TMP-35g (both warning-emitting cleanup-safety branches). Drive via `runAPIDriverLive()`: `const c = new AbortController(); const gen = run("ralph", { signal: c.signal }); const nextP = gen.next();` `await waitForStderr("ready")`. Call `c.abort()`. `await expect(nextP).rejects.toThrow(<abort error>)`. Assert per variant: (a) the generator throws the **abort** error (matching T-API-10's abort-error contract), (b) stderr contains exactly one cleanup-related warning, and (c) for the regular-file-replacement variant the `$LOOPX_TMPDIR` path still exists as a regular file; for the mismatched-directory variant the path still exists as a directory with the `mismatched-marker` file inside. The active child must also be terminated. Together with T-TMP-35f (CLI signal terminal), T-TMP-35g (`runPromise()` abort terminal), this closes the cleanup-warning-does-not-affect-outcome coverage across all three surfaces × all four terminal types — success (T-TMP-35 / T-TMP-35a / T-TMP-35b / T-TMP-36 / T-TMP-36a / T-TMP-36b), script-error (T-TMP-35c / T-TMP-35d / T-TMP-35e), signal (T-TMP-35f), abort (T-TMP-35g / T-TMP-35h) — × both warning-emitting cleanup-safety branches (regular-file replacement and mismatched-directory replacement). *(Spec 7.4, 9.1, 12)*
+- **T-TMP-36**: Cleanup leaves a mismatched-directory replacement in place with a warning. Fixture observes `LOOPX_TMPDIR`, then **renames the original tmpdir aside** (`mv "$LOOPX_TMPDIR" "$LOOPX_TMPDIR-original-aside"`) and creates a **different** directory at the original path (`mkdir "$LOOPX_TMPDIR" && touch "$LOOPX_TMPDIR/mismatched-marker"`). The rename-aside step is essential for inode-distinctness: a naive `rm -rf "$LOOPX_TMPDIR" && mkdir "$LOOPX_TMPDIR"` could let the kernel reuse the original directory's inode for the freshly-created directory on POSIX filesystems where inode allocation does not strictly avoid recently-freed values, which would make the new directory's inode coincidentally match loopx's captured identity fingerprint and the test would observe a successful (rather than mismatched) cleanup — an unrelated kernel-implementation accident, not a SPEC-conformance signal. By keeping the original directory alive at a different path, its inode remains occupied for the lifetime of the script (the test harness cleans up `-original-aside` after the assertions), guaranteeing the freshly-created directory at `$LOOPX_TMPDIR` is allocated a distinct inode. The new directory's device/inode therefore differs from the identity fingerprint loopx captured at tmpdir creation, making it a mismatched directory per SPEC 7.4 rule 5. Script emits `stop:true`. After loopx exits 0, assert: (a) the `$LOOPX_TMPDIR` path still exists and is a directory, (b) the `mismatched-marker` file inside still exists — loopx did not recursively remove it (the filesystem-safety outcome per SPEC 7.4 rule 5), (c) stderr contains exactly one cleanup-related warning (per-run cleanup-warning cardinality), (d) the CLI exit code is 0, and (e) the renamed-aside copy at `$LOOPX_TMPDIR-original-aside` still exists with its original content (loopx did not chase the renamed-away tmpdir, per the SPEC 7.4 "no chasing renamed tmpdirs" rule already covered by T-TMP-33 — and as a side effect of this rename-aside fixture pattern, this assertion provides incidental defense-in-depth for that contract). The warning text is implementation-defined per SPEC 7.4; do **not** require it to mention the path, the directory-identity mismatch, or any specific phrasing — only that a single cleanup-related warning is emitted. Per SPEC 7.4 rule 5: "Path is a directory whose identity does not match: leave in place with a stderr warning." *(Spec 7.4)*
+- **T-TMP-36a**: `runPromise()` outcome is unaffected by a cleanup warning (mismatched-directory replacement). Programmatic-API counterpart to T-TMP-36, matching the pattern of T-TMP-35a. Use the same fixture (script observes `LOOPX_TMPDIR`, renames it aside, creates a distinct-inode replacement at the path, emits `stop: true`). Call `runPromise("ralph", { maxIterations: 1 })`. Capture driver-process stderr. Assert: (a) the promise **resolves** (does not reject), (b) the resolved array's single `Output` has `stop: true`, (c) the captured stderr contains exactly one cleanup-related warning, and (d) the `$LOOPX_TMPDIR` path still exists as a directory with the `mismatched-marker` file inside (the filesystem-safety rule held). Per SPEC 7.4: "cleanup warnings do not affect ... the promise rejection reason." *(Spec 7.4, 9.2)*
+- **T-TMP-36b**: `run()` generator outcome is unaffected by a cleanup warning (mismatched-directory replacement). Generator-surface counterpart to T-TMP-36a. Same fixture; drive via `for await` until the generator completes naturally. Assert: (a) the `for await` loop iterates the single `Output` with `stop: true` and then completes without throwing, (b) stderr contains exactly one cleanup-related warning, and (c) the `$LOOPX_TMPDIR` path still exists with `mismatched-marker` intact. Together with T-TMP-36 (CLI) and T-TMP-36a (`runPromise`), closes the cleanup-warning-does-not-affect-outcome coverage across all three surfaces for the mismatched-directory branch. Per SPEC 7.4: "cleanup warnings do not affect ... the generator outcome." *(Spec 7.4, 9.1)*
+- **T-TMP-37**: Recursive cleanup unlinks nested symlink entries without traversing targets, and emits **no** cleanup warning. Fixture observes `LOOPX_TMPDIR`, creates an external target (e.g., `$LOOPX_PROJECT_ROOT/external-target-dir/` containing `external-file`), then creates a nested symlink `$LOOPX_TMPDIR/nested-link -> $LOOPX_PROJECT_ROOT/external-target-dir`, emits `stop:true`. After loopx exits 0, assert: (a) `$LOOPX_TMPDIR` has been removed (recursive cleanup ran, matching identity), (b) `$LOOPX_PROJECT_ROOT/external-target-dir/` still exists with `external-file` intact — the recursive walk unlinked the nested symlink entry but did not follow through to delete its target contents, and (c) **stderr contains no cleanup-related warning** — SPEC 7.4 rule 4 ("Path is a directory whose identity matches the recorded identity: recursively remove. Symlink entries encountered during the walk are unlinked but not traversed") is the success path of recursive cleanup; warnings are emitted only on cleanup-failure or rules 3 / 5. The presence of nested symlinks does not change which rule applies — the top-level entry is still a matching directory, the recursive walk handles each nested entry per its own type, and the whole operation succeeds without producing a warning when no failure / non-directory / mismatched-directory condition is hit. This assertion mirrors T-TMP-34's no-warning-on-success contract for the recursive-cleanup-with-nested-symlinks branch, distinguishing "successful recursive cleanup with nested symlink" from "recursive cleanup encountered an unlink failure on a nested symlink" (which would emit a single warning per the cleanup-failure clause). The cleanup-warning text format is implementation-defined per SPEC 7.4 warning-text-broadness convention; the assertion here is **negative** (no cleanup-related warning emitted at all on stderr). Per SPEC 7.4 rule 4: "Symlink entries encountered during the walk are unlinked but not traversed, so symlinks pointing outside the tmpdir do not collateral-delete their targets." *(Spec 7.4)*
+- **T-TMP-37a**: Cleanup leaves a FIFO replacement in place with a warning. SPEC 7.4's cleanup-safety rule 3 applies to "a regular file or other non-directory non-symlink entry" — the rule names regular files, FIFOs (named pipes), and sockets as representative non-directory non-symlink types. T-TMP-35 covers the regular-file branch; this test covers the FIFO branch as a representative additional non-directory type, proving the rule is not special-cased to regular files. Fixture `.loopx/ralph/index.sh` observes `LOOPX_TMPDIR`, then `rm -rf "$LOOPX_TMPDIR"` and `mkfifo "$LOOPX_TMPDIR"` (tmpdir path is now a FIFO), then emits `stop:true`. After loopx exits 0, assert: (a) the `$LOOPX_TMPDIR` path still exists and is a FIFO (`stat -c '%F' "$LOOPX_TMPDIR" == "fifo"` or the POSIX-equivalent mode check via `fs.lstatSync(path).isFIFO()`) — loopx did not unlink the FIFO, following rule 3's "leave in place with a stderr warning" for non-directory non-symlink entries, (b) stderr contains exactly one cleanup-related warning (per-run cleanup-warning cardinality rule from SPEC 7.4), (c) the CLI exit code is 0 (the cleanup warning does not affect the exit code, matching T-TMP-35's same clause). The warning text is implementation-defined per SPEC 7.4 warning-text-broadness convention; do not pin specific phrasing. Together with T-TMP-35 (regular file) this establishes that rule 3 covers at least two distinct non-directory types (regular file and FIFO), sufficient to prove the rule is typed generically rather than narrowly special-cased. **Conditional on the test harness being able to `mkfifo` — standard POSIX; not conditional on privileged operations.** *(Spec 7.4)*
+- **T-TMP-37b**: Cleanup leaves a Unix-domain socket replacement in place with a warning. SPEC 7.4 cleanup-safety rule 3 explicitly names sockets alongside regular files and FIFOs as representative non-directory non-symlink entries: "Path is a regular file, FIFO, socket, or other non-directory non-symlink: leave in place with a stderr warning." T-TMP-35 covers the regular-file branch and T-TMP-37a covers the FIFO branch; this test covers the socket branch, completing direct coverage for all three explicitly-named non-directory types in SPEC 7.4 rule 3. Fixture `.loopx/ralph/index.ts` (or `.js` — TS/JS is required because creating a Unix-domain socket from a portable bash one-liner is awkward, while Node's `net.createServer().listen(<path>)` reliably binds a `SOCK_STREAM` Unix-domain socket at a path on every POSIX runtime targeted by this suite) observes `LOOPX_TMPDIR` via `process.env.LOOPX_TMPDIR`, writes its value to a marker file for the post-run assertion, then `fs.rmSync(tmpdirPath, { recursive: true, force: true })` and `await new Promise(resolve => { const server = net.createServer(); server.listen(tmpdirPath, resolve); })` (the path is now a bound Unix-domain socket entry — `lstat` returns a socket-typed inode), keeps a reference to `server` until `output({ stop: true })` is emitted (so the socket entry is alive at cleanup time), and then exits. After loopx exits 0, assert: (a) the `$LOOPX_TMPDIR` path still exists and is a Unix-domain socket (`fs.lstatSync(path).isSocket()` returns `true`) — loopx did not unlink the socket, following rule 3's "leave in place with a stderr warning" for non-directory non-symlink entries, (b) stderr contains **exactly one** cleanup-related warning (per-run cleanup-warning cardinality rule from SPEC 7.4), and (c) the CLI exit code is `0` (the cleanup warning does not affect the exit code, matching T-TMP-35 and T-TMP-37a). The warning text is implementation-defined per SPEC 7.4 warning-text-broadness convention; do not pin specific phrasing. Together with T-TMP-35 (regular file) and T-TMP-37a (FIFO), this test closes coverage for all three SPEC 7.4 rule-3-enumerated non-directory types — proving the rule is typed generically (any non-directory non-symlink is left in place with a warning) rather than special-cased to regular files or FIFO/regular-file pairs. The harness cleanup step removes the leftover socket entry under the test-isolated tmpdir parent after the assertions, matching the cleanup pattern T-TMP-35 / T-TMP-37a use for the regular-file / FIFO leftovers. **Standard POSIX (Linux, macOS); not conditional on privileged operations** — Unix-domain socket creation is unprivileged on POSIX systems and is a baseline capability of the Node and Bun `net` modules used elsewhere in this suite. *(Spec 7.4)*
+- **T-TMP-37c**: Cleanup leaves a hard-link replacement in place with a warning, **and the external hard-linked file's `nlink` count is unchanged**. SPEC 7.4 cleanup-safety rule 3 explicitly cites hard-link `nlink` decrement as the underlying rationale: "Unlinking would risk mutating unrelated data (hard-link `nlink` decrement, or data renamed into the path with `nlink == 1`)." T-TMP-35 covers the regular-file branch and asserts the file content remains, but does not prove the `nlink`-decrement-safety guarantee — T-TMP-35's fixture has only one filesystem reference to the regular file, so an erroneous unlink would simply remove the file, not decrement an unrelated reference, and the `nlink`-safety contract that SPEC 7.4 rule 3 names by reference is unexercised. This test pins down the explicit `nlink`-safety guarantee. **Setup.** Outside the tmpdir, create an external regular file (e.g., `$LOOPX_PROJECT_ROOT/external-target-file` containing `external-content`). Fixture `.loopx/ralph/index.sh` observes `LOOPX_TMPDIR` into a marker, captures the external file's path into the marker as well (so the harness can post-run `lstat` it), then `rm -rf "$LOOPX_TMPDIR"` and `ln "$LOOPX_PROJECT_ROOT/external-target-file" "$LOOPX_TMPDIR"` — the tmpdir path is now a **hard link** to the external file, with both paths sharing the same inode and `nlink == 2`. Before exiting, the script captures the pre-cleanup `nlink` count of the external path via `stat -c '%h' "$LOOPX_PROJECT_ROOT/external-target-file"` (or the POSIX-equivalent `fs.lstatSync(path).nlink`) into a separate marker file (`pre-cleanup-nlink`); reading from the external path is reliable because the external path is not under the tmpdir and thus is not subject to cleanup. Then the script emits `stop:true`. After loopx exits 0, the harness asserts: (a) the `$LOOPX_TMPDIR` path **still exists** (loopx did not unlink the hard-link entry — SPEC 7.4 rule 3 leaves it in place), (b) the external `$LOOPX_PROJECT_ROOT/external-target-file` path also still exists with content `external-content` (loopx did not follow the hard link or otherwise mutate the external path), (c) the post-cleanup `nlink` count of the external path (read by the harness via `fs.lstatSync(externalPath).nlink`) **equals the pre-cleanup `nlink` count recorded in the marker** — both should be `2`, proving loopx did not unlink the tmpdir-side hard link entry (which would have decremented `nlink` to `1` on the external file), (d) the post-cleanup `nlink` count of the **tmpdir-side** path (`fs.lstatSync(tmpdirPath).nlink`) is also unchanged at `2` — both ends of the hard-link pair preserved the `nlink` count, (e) the post-cleanup `lstat` of the tmpdir path and the external path return the **same inode** (`fs.lstatSync(tmpdirPath).ino === fs.lstatSync(externalPath).ino`) — the hard-link relationship is intact, (f) stderr contains exactly one cleanup-related warning (per-run cleanup-warning cardinality from SPEC 7.4, matching T-TMP-35 / T-TMP-36 / T-TMP-37a / T-TMP-37b), (g) the CLI exit code is 0 (terminal outcome unaffected by the cleanup warning, matching T-TMP-35a / T-TMP-35b / T-TMP-36a / T-TMP-36b's "warnings do not affect outcome" contract). The warning text is implementation-defined per SPEC 7.4 warning-text-broadness convention; do not pin specific phrasing. A buggy implementation that classified the hard-link tmpdir entry as "ordinary regular file, safe to unlink because it has content we don't care about" would unlink it, decrementing `nlink` to `1` on the external path and failing assertion (c) — even though the external file would still exist with its content (the unlink only removes the tmpdir-side entry), the `nlink` change is observable and is precisely the unrelated-data mutation SPEC 7.4 rule 3 forbids. Together with T-TMP-35 (regular file with `nlink == 1`), T-TMP-37a (FIFO), and T-TMP-37b (socket), this test closes coverage for the SPEC 7.4 rule-3 hard-link-safety sub-clause that the existing single-`nlink` regular-file test cannot exercise. **Standard POSIX (Linux, macOS); not conditional on privileged operations** — `ln` (without `-s`) creates a hard link unprivileged when source and target are on the same filesystem; the test's project root and tmpdir parent must therefore be on the same device, and the harness asserts `fs.lstatSync(externalPath).dev === fs.lstatSync(tmpdirPath).dev` during setup, skipping with a clear message if cross-device prevents the hard link. The harness cleanup step removes both paths (the hard link from the tmpdir parent, the external file from the project) after the assertions. *(Spec 7.4)*
+
+##### Cleanup-Safety Failure Branches
+
+SPEC 7.4 specifies a final paragraph after the identity-fingerprint dispatch rules: "If the top-level `lstat` fails for any reason other than ENOENT, the `unlink` in case 2 fails, or the recursive removal in case 4 fails, loopx emits a single stderr warning and makes no further changes." These three failure branches are specified normatively. Black-box reproduction is unreliable on a same-user-owned directory, so T-TMP-40 / T-TMP-41 / T-TMP-42 cover them deterministically via the section 1.4 `LOOPX_TEST_CLEANUP_FAULT` seam.
+
+- **T-TMP-40**: Top-level cleanup `lstat` failure (non-ENOENT). Set `NODE_ENV=test` and `LOOPX_TEST_CLEANUP_FAULT=lstat-fail` so the cleanup routine observes a simulated `EACCES` from the top-level `lstat` on `$LOOPX_TMPDIR` (per the section 1.4 seam contract). Fixture `.loopx/ralph/index.sh` observes `LOOPX_TMPDIR` into a marker external to the tmpdir and emits `stop:true`. **Parameterize over the three execution surfaces** (CLI / `run()` / `runPromise()`) — each surface drives the script to natural completion so cleanup runs. Assert per surface: (a) the surface-appropriate **success** terminal outcome surfaces (CLI exit 0 / generator settles cleanly without throwing / promise resolves) — per SPEC 7.4 "cleanup warnings do not affect the CLI exit code, the generator outcome, or the promise rejection reason," (b) **stderr contains exactly one cleanup-related warning** — the SPEC 7.4 "single stderr warning, no further changes" rule, and (c) the path observed in the marker still exists on disk (no further cleanup changes happened after the simulated `lstat` failure — loopx emitted the warning and stopped). The warning text is implementation-defined per SPEC 7.4 warning-text-broadness convention; do not pin specific phrasing. *(Spec 7.4)*
+- **T-TMP-41**: Symlink `unlink` failure during cleanup (rule 2 failure). Set `NODE_ENV=test` and `LOOPX_TEST_CLEANUP_FAULT=symlink-unlink-fail` so the cleanup routine observes a simulated `EACCES` on the rule-2 `unlink` (per the section 1.4 seam contract; the seam fires only when the cleanup dispatch reaches rule 2, i.e., when the path is a symlink). Fixture `.loopx/ralph/index.sh` observes `LOOPX_TMPDIR` into an external marker, then performs `rm -rf "$LOOPX_TMPDIR" && ln -s /tmp "$LOOPX_TMPDIR"` so the path becomes a symlink (replacing the directory loopx created), and emits `stop:true`. **Parameterize over the three execution surfaces** (CLI / `run()` / `runPromise()`). Drive the script to natural completion. Assert per surface: (a) the success terminal outcome surfaces (the cleanup warning does not affect outcome per SPEC 7.4), (b) stderr contains exactly one cleanup-related warning, and (c) the symlink still exists at the recorded path (loopx made no further changes after the simulated `unlink` failure — the symlink that the script created is preserved). The harness cleanup step removes the symlink after the assertions. *(Spec 7.4)*
+- **T-TMP-42**: Recursive removal failure on identity-matched directory (rule 4 failure). Set `NODE_ENV=test` and `LOOPX_TEST_CLEANUP_FAULT=recursive-remove-fail` so the cleanup routine observes a simulated `EACCES` during the rule-4 recursive walk (per the section 1.4 seam contract; the seam fires only when the cleanup dispatch reaches rule 4, i.e., when the path is an identity-matched directory). Fixture `.loopx/ralph/index.sh` observes `LOOPX_TMPDIR` into an external marker, writes a few files inside (`echo content > "$LOOPX_TMPDIR/file-1"`, `mkdir "$LOOPX_TMPDIR/sub" && echo more > "$LOOPX_TMPDIR/sub/file-2"`), and emits `stop:true`. **Parameterize over the three execution surfaces** (CLI / `run()` / `runPromise()`). Drive the script to natural completion. Assert per surface: (a) the success terminal outcome surfaces (cleanup warning does not affect outcome — SPEC 7.4), (b) stderr contains exactly one cleanup-related warning (per-run cleanup-warning cardinality), and (c) the path observed in the marker still exists (loopx made no further changes after the simulated recursive-remove failure — the partial walk's effect on disk is implementation-defined, but the SPEC contract is "no further changes" after the warning is emitted, so the path itself remains visible at the originally recorded location). The harness cleanup step removes any leftover content under the test-isolated tmpdir parent. *(Spec 7.4)*
+- **T-TMP-42a**: Cleanup-fault warning does not mask **non-zero script exit** as the surfaced outcome. SPEC 7.4 says "cleanup warnings do not affect the CLI exit code, the generator outcome, or the promise rejection reason" — the contract holds for both the **cleanup-safety warning branch** (rule-3 non-directory and rule-5 mismatched-directory leave-in-place warnings, covered by T-TMP-35d / T-TMP-35e for the script-error terminal) and the **cleanup-failure warning branch** (rule-4 recursive-remove failure and the other `LOOPX_TEST_CLEANUP_FAULT` seams). T-TMP-40 / T-TMP-41 / T-TMP-42 cover the cleanup-failure warning branch on the **success** terminal across all three surfaces; T-TMP-35d / T-TMP-35e cover the cleanup-**safety** warning branch on the script-error terminal. The combination — cleanup-failure warning branch × script-error terminal — is the missing diagonal. A buggy implementation that wired one stream of "warnings do not mask outcome" handling for rule-3 / rule-5 leave-in-place warnings (passing T-TMP-35d / T-TMP-35e) and a separate stream for rule-4 / lstat-fail / symlink-unlink-fail cleanup-failure warnings (where the second stream might wrap or replace the script-error rejection) would pass T-TMP-40–42 (success terminal) and T-TMP-35d–35e (cleanup-safety branch) and fail this test. **Parameterize over the three cleanup-fault seam values** (`lstat-fail`, `symlink-unlink-fail`, `recursive-remove-fail`) so the warning-not-masking guarantee is pinned across all three SPEC 7.4 cleanup-failure branches. **Parameterize over the three execution surfaces** (CLI / `run()` / `runPromise()`). For each (seam, surface) combination, set `NODE_ENV=test` and `LOOPX_TEST_CLEANUP_FAULT=<seam>`. Fixture `.loopx/ralph/index.sh` observes `LOOPX_TMPDIR` into an external marker, performs the seam-specific path manipulation if needed (for `symlink-unlink-fail`: `rm -rf "$LOOPX_TMPDIR" && ln -s /tmp "$LOOPX_TMPDIR"` so cleanup dispatch reaches rule 2; for `recursive-remove-fail`: writes a few files inside; for `lstat-fail`: no path manipulation needed, the seam fires on the top-level `lstat`), then **exits non-zero** (e.g., `exit 1`) without emitting a `stop`. Drive the script to natural completion. Assert per (seam, surface): (a) the surface-appropriate **non-zero-exit** terminal outcome surfaces — CLI exit 1 / generator throws a script-failure error / promise rejects with a script-failure error — **the original script-failure outcome is preserved**, not masked or replaced by a cleanup-failure outcome, (b) stderr contains exactly one cleanup-related warning (the seam-induced warning; per-run cleanup-warning cardinality from SPEC 7.4 still holds under the script-error terminal), and (c) for the `symlink-unlink-fail` seam the path manipulated by the script still exists at the recorded location (no further cleanup changes happened after the warning); for `recursive-remove-fail` the path still exists; for `lstat-fail` the path still exists (the seam fires on the top-level `lstat`, so loopx never reaches the dispatch rules). A buggy implementation that promoted the cleanup-failure warning to a cleanup-failure-class rejection (CLI exit 2, or a wrapped error class on the API) under the script-error terminal would fail (a). The harness cleanup step removes any leftover content under the test-isolated tmpdir parent and the symlink (for `symlink-unlink-fail`) after the assertions. *(Spec 7.4, 7.2, 9.1, 9.2)*
+- **T-TMP-42b**: Cleanup-fault warning does not mask the **abort** as the surfaced outcome. Companion to T-TMP-42a covering the abort terminal axis. SPEC 7.4 says "cleanup warnings do not affect the generator outcome, or the promise rejection reason"; T-TMP-35g / T-TMP-35h cover the cleanup-**safety** warning branch on the abort terminal across `runPromise()` and `run()`; this test pins down the cleanup-**failure** warning branch on the same terminal. The combination — cleanup-failure warning branch × abort terminal — is the second missing diagonal (T-TMP-42a closes the script-error diagonal). **Parameterize over the three cleanup-fault seam values** (`lstat-fail`, `symlink-unlink-fail`, `recursive-remove-fail`) and over the **two programmatic surfaces** (`run()` / `runPromise()`). For each (seam, surface) combination, set `NODE_ENV=test` and `LOOPX_TEST_CLEANUP_FAULT=<seam>`. Fixture `.loopx/ralph/index.sh` observes `LOOPX_TMPDIR` into an external marker, performs the seam-specific path manipulation if needed (same per-seam pattern as T-TMP-42a), writes its PID to a separate marker, writes `"ready"` to stderr, then **blocks indefinitely** (so the script is still running when the harness fires the abort). Use `runAPIDriverLive()` to obtain a driver-process handle. Drive: `const c = new AbortController();` then for `runPromise`: `const promise = runPromise("ralph", { signal: c.signal });` for `run`: `const gen = run("ralph", { signal: c.signal }); const nextP = gen.next();`. `await waitForStderr("ready")` on the driver stream. Capture driver-process stderr for the duration of the operation. Call `c.abort()` from the harness via the driver-handle coordination mechanism (mirroring T-TMP-35g / T-TMP-35h's coordination pattern). For `runPromise`: `await expect(promise).rejects.toThrow(<abort error>)`; for `run`: `await expect(nextP).rejects.toThrow(<abort error>)`. Assert per (seam, surface): (a) the operation rejects / throws with the **abort** error — **the original abort outcome is preserved**, not masked or replaced by a cleanup-failure outcome, (b) stderr contains exactly one cleanup-related warning (the seam-induced warning; per-run cleanup-warning cardinality still holds under the abort terminal), (c) the active child is terminated (the script's PID from the marker is no longer running — abort-driven process-group termination from T-API-10d's contract still applies even under the cleanup-failure branch), and (d) the seam-specific path persistence assertion from T-TMP-42a applies (the path manipulated by the script for `symlink-unlink-fail` still exists; for `recursive-remove-fail` the path still exists; for `lstat-fail` the path still exists). A buggy implementation that promoted the cleanup-failure warning to a cleanup-failure-class rejection in place of the abort error would fail (a). Together with T-TMP-42a (script-error × cleanup-failure), this closes the cleanup-failure-warning-branch × error-terminal coverage axis on both error terminals (script-error and abort), distinguishing the cleanup-safety-warning branch (T-TMP-35d / 35e / 35g / 35h) from the cleanup-failure-warning branch on every error terminal. *(Spec 7.4, 7.2, 9.1, 9.2, 9.3)*
+- **T-TMP-42c**: Cleanup-fault warning does not mask the **signal** as the surfaced outcome (CLI surface). SPEC 7.4 says "cleanup warnings do not affect the CLI exit code" — the contract holds for both the cleanup-**safety** warning branch and the cleanup-**failure** warning branch. T-TMP-35f covers the cleanup-safety warning branch on the signal terminal across both signals × both warning-emitting cleanup-safety branches; T-TMP-40 / T-TMP-41 / T-TMP-42 cover the cleanup-failure warning branch on the **success** terminal across all three surfaces; T-TMP-42a covers cleanup-failure × script-error (CLI / `run()` / `runPromise()`); T-TMP-42b covers cleanup-failure × abort (`run()` / `runPromise()`, abort being programmatic-only). The combination — cleanup-failure warning branch × **CLI signal** terminal — is the third missing diagonal: T-TMP-35f closes the cleanup-safety side of the signal terminal, but no test currently pins down the cleanup-failure side under SIGINT / SIGTERM. A buggy implementation that wired the signal-terminal `128 + signal number` exit-code path correctly for rule-3 / rule-5 cleanup-safety warnings (passing T-TMP-35f) and a separate stream for rule-4 / `lstat-fail` / `symlink-unlink-fail` cleanup-failure warnings (where the second stream might promote the cleanup-failure warning to a cleanup-failure-class exit code under signal — e.g., exit `1` or an implementation-specific cleanup-failure code instead of the signal code) would pass T-TMP-35f and T-TMP-40 / T-TMP-41 / T-TMP-42 / T-TMP-42a / T-TMP-42b and fail this test. **Parameterize over the three cleanup-fault seam values** (`lstat-fail`, `symlink-unlink-fail`, `recursive-remove-fail`) **and over both signals** (SIGINT and SIGTERM) — six sub-cases total. For each (seam, signal) combination, set `NODE_ENV=test` and `LOOPX_TEST_CLEANUP_FAULT=<seam>`. Fixture `.loopx/ralph/index.sh` observes `LOOPX_TMPDIR` into an external marker (path external to the tmpdir so it survives cleanup), performs the seam-specific path manipulation if needed (for `symlink-unlink-fail`: `rm -rf "$LOOPX_TMPDIR" && ln -s /tmp "$LOOPX_TMPDIR"` so cleanup dispatch reaches rule 2; for `recursive-remove-fail`: writes a few files inside the tmpdir, e.g., `echo content > "$LOOPX_TMPDIR/file-1" && mkdir "$LOOPX_TMPDIR/sub" && echo more > "$LOOPX_TMPDIR/sub/file-2"`; for `lstat-fail`: no path manipulation needed, the seam fires on the top-level `lstat`), writes `"ready"` to stderr, then **blocks indefinitely** (`while true; do sleep 1; done`). Run via `runCLIWithSignal`. Wait for `"ready"` on stderr, then send the variant-specific signal (SIGINT or SIGTERM) to loopx. Assert per (seam, signal): (a) loopx exits with the **signal exit code** — `130` for SIGINT, `143` for SIGTERM (the cleanup-failure warning did not mask, replace, or override the signal exit code; this is the load-bearing assertion), (b) stderr contains exactly one cleanup-related warning (the seam-induced warning; per-run cleanup-warning cardinality from SPEC 7.4 still holds under the signal terminal — the signal does not double the warning emission), and (c) for the `symlink-unlink-fail` seam the symlink at the recorded path still exists (no further cleanup changes happened after the warning); for `recursive-remove-fail` the path observed in the marker still exists (the partial walk's effect on inner files is implementation-defined per SPEC 7.4's "no further changes" wording, but the path itself remains visible at the recorded location); for `lstat-fail` the path still exists (the seam fires on the top-level `lstat`, so loopx never reaches the dispatch rules). A buggy implementation that promoted the cleanup-failure warning to a cleanup-failure-class exit code under the signal terminal (e.g., exit `1` instead of the signal code, or some implementation-specific cleanup-failure code) would fail (a) on every sub-case. The harness cleanup step removes any leftover content under the test-isolated tmpdir parent and the symlink (for `symlink-unlink-fail`) after the assertions. Together with T-TMP-35f (cleanup-safety × signal × CLI), T-TMP-40 / T-TMP-41 / T-TMP-42 (cleanup-failure × success × all surfaces), T-TMP-42a (cleanup-failure × script-error × all surfaces), and T-TMP-42b (cleanup-failure × abort × programmatic surfaces), this completes the cleanup-warning-does-not-affect-outcome coverage axis for the cleanup-failure branch across all four terminal types — success, script-error, signal, abort — closing the remaining "cleanup warnings do not affect CLI exit code" axis for cleanup-failure warnings on the signal terminal. *(Spec 7.4, 7.3, 12)*
+
+##### Cleanup Idempotence and Warning Cardinality
+
+SPEC 7.2 / 7.4 specify strong guarantees around cleanup:
+
+- **At most one cleanup attempt per created `LOOPX_TMPDIR`** over the lifetime of the run — racing terminal triggers (SIGTERM during cleanup of a prior SIGINT; abort concurrent with consumer `.return()` / `.throw()`; non-zero exit concurrent with abort; abort after final yield concurrent with a consumer `.throw()`; child spawn failure concurrent with abort; abort concurrent with tmpdir creation failure) do not start a second cleanup attempt.
+- **At most one cleanup-related stderr warning per run.** Combined with the idempotence rule, every run emits at most one cleanup warning regardless of how many concurrent terminal triggers or cleanup-safety rules fire.
+
+Existing T-TMP-35 / T-TMP-36 assert "a single cleanup warning" for the regular-file-replacement and mismatched-directory-replacement cases respectively, which are the two normatively-warning cleanup-safety branches. T-TMP-38 / T-TMP-39 cover the **racing-trigger idempotence** and **at-most-one-warning across racing triggers** guarantees deterministically via the section 1.4 `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE=cleanup-start` seam, which pauses loopx at the entry of the cleanup routine and lets the harness inject a second terminal trigger before cleanup proceeds.
+
+- **T-TMP-38**: Cleanup idempotence under racing SIGINT → SIGTERM. Set `NODE_ENV=test`, `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE=cleanup-start`, and `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE_MARKER=<absolute-path>` (per the section 1.4 seam contract; the marker path is outside `$LOOPX_TMPDIR` so it survives loopx's exit). Fixture `.loopx/ralph/index.sh` observes `LOOPX_TMPDIR` into a marker external to the tmpdir, then renames it aside and creates a regular-file replacement (`rm -rf "$LOOPX_TMPDIR" && printf '%s' "regular-file-replacement" > "$LOOPX_TMPDIR"` — the rule-3 cleanup-warning-emitting branch from T-TMP-35), writes `"ready"` to stderr, then blocks indefinitely. Run via `runCLIWithSignal`. Wait for `"ready"` on stderr, then send **SIGINT** to loopx; the SIGINT triggers the terminal cleanup path. The seam pauses loopx at cleanup start and writes the parent-observable marker. The harness polls for the marker file, then sends a **second signal (SIGTERM)** to loopx during the bounded pause. After the pause resumes, loopx completes cleanup. Assert: (a) loopx exits with the SIGINT exit code **130** (the first-observed signal — SPEC 7.2 first-trigger-wins; the post-cleanup-start SIGTERM does not displace the first signal's exit code), (b) **stderr contains exactly one cleanup-related warning** (the rule-3 warning was emitted during the single cleanup attempt; no second cleanup attempt and therefore no second warning), and (c) the regular-file replacement at the recorded tmpdir path still exists with content `regular-file-replacement` (cleanup completed once, leaving the rule-3 path in place, with no double-cleanup attempt). A buggy implementation that started a second cleanup attempt on the second signal would produce a second cleanup-related warning and fail (b). `@flaky-retry(2)`. *(Spec 7.2, 7.4)*
+- **T-TMP-39**: At-most-one-warning cardinality across racing terminal triggers. Companion to T-TMP-38 — same fixture, same seam configuration, but with the **mismatched-directory** rule-5 cleanup-warning branch (using the T-TMP-36 rename-aside pattern: `mv "$LOOPX_TMPDIR" "$LOOPX_TMPDIR-aside" && mkdir "$LOOPX_TMPDIR" && touch "$LOOPX_TMPDIR/mismatched-marker"`) instead of the regular-file rule-3 branch. This pins down the warning-cardinality contract on the mismatched-directory branch — a buggy implementation could plausibly use one warning-emitter for rule-3 and a separate one for rule-5, with the race-coordination logic correct for rule-3 (passing T-TMP-38) but incorrect for rule-5. Drive via `runCLIWithSignal` with the same SIGINT-then-SIGTERM-during-pause harness pattern as T-TMP-38. Assert: (a) loopx exits with code 130 (first-observed SIGINT), (b) **stderr contains exactly one cleanup-related warning** (the rule-5 mismatched-directory warning), and (c) the mismatched-directory replacement at the recorded tmpdir path still exists with the `mismatched-marker` file inside (cleanup completed once, leaving the rule-5 path in place). The renamed-aside copy at `$LOOPX_TMPDIR-aside` also still exists with its original content (loopx did not chase the renamed-away tmpdir, matching T-TMP-36's rename-aside no-chasing assertion). The harness cleanup step removes both the mismatched-directory replacement and the rename-aside copy after the assertions. `@flaky-retry(2)`. *(Spec 7.2, 7.4)*
+- **T-TMP-38a**: Cleanup idempotence on the programmatic `run()` surface — abort observed first, racing `.return()` during cleanup-start does not start a second cleanup attempt. SPEC 7.2's "Racing terminal triggers ... do not start a second cleanup attempt" enumeration explicitly names "abort concurrent with consumer `.return()` / `.throw()`" as a covered race. T-TMP-38 / T-TMP-39 cover the CLI signal-vs-signal race; this test closes the equivalent contract on the programmatic surface where the first-observed trigger is an abort and the racing second trigger is a consumer `.return()` arriving during cleanup. Set `NODE_ENV=test`, `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE=cleanup-start`, and `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE_MARKER=<absolute-path>`. Fixture `.loopx/ralph/index.sh` observes `LOOPX_TMPDIR` into an external marker, then performs the rule-3 regular-file replacement (`rm -rf "$LOOPX_TMPDIR" && printf '%s' "regular-file-replacement" > "$LOOPX_TMPDIR"` so the cleanup path emits a warning), writes `"ready"` to stderr, then sleeps 30 seconds. Drive via `runAPIDriverLive()`: `const c = new AbortController(); const gen = run("ralph", { signal: c.signal });` Call `gen.next()` to enter the loop body. `await waitForStderr("ready")`. Call `c.abort()` — loopx observes the abort first, terminates the script (per SPEC 9.1 abort handling), and enters the cleanup routine. The seam pauses cleanup at start and writes the parent-observable marker. The harness polls for the marker, then calls `gen.return(undefined)` during the bounded pause (this is a mid-loop `.return()` racing with the in-progress cleanup). After loopx resumes, await the generator's settlement. Assert: (a) the generator settles by **throwing an abort error** (the first-observed trigger — SPEC 7.2 first-trigger-wins; the post-cleanup-start `.return()` does not displace the abort outcome), (b) **stderr contains exactly one cleanup-related warning** (the rule-3 warning from the single cleanup attempt; no second cleanup attempt and therefore no second warning — the SPEC 7.2 / 7.4 idempotence contract), and (c) the regular-file replacement at the recorded tmpdir path still exists with content `regular-file-replacement` (cleanup completed once and left the rule-3 path in place; no double cleanup attempt). A buggy implementation that started a second cleanup attempt on the racing `.return()` would produce a second warning and fail (b); an implementation that surfaced a clean `.return()` settlement would fail (a). `@flaky-retry(2)`. *(Spec 7.2, 7.4, 9.1)*
+- **T-TMP-38a2**: Cleanup idempotence on the programmatic `run()` surface — **mid-loop `.return()` observed first**, racing abort during cleanup-start does not start a second cleanup attempt and emits at most one cleanup warning. Symmetric counterpart to T-TMP-38a for the `.return()`-first × abort-second observation order on the warning-cardinality axis; closes the matrix-symmetry gap for SPEC 7.2's "abort concurrent with consumer `.return()` / `.throw()`" enumeration on the `.return()` axis. T-TMP-38a covers the abort-first × `.return()`-second order (where SPEC 7.2's first-observed-wins rule pins the surfaced outcome to the abort error); this test covers the inverted order, where `.return()` is observed first and the post-pause abort does not displace the clean `.return()` settlement (per the same first-observed-wins rule, applied symmetrically to T-TERM-02 variant b's mid-loop precedent on the surfaced-outcome axis). T-TERM-02 variant b covers the **outcome** axis of this race on a non-warning-emitting fixture (script blocks, no tmpdir mutation, cleanup runs without warning), but its assertion that "the generator settles cleanly with the `.return()` value" cannot distinguish single-cleanup-attempt from double-cleanup-attempt code paths — both single and double cleanup of an empty rule-4 directory are warning-free and outcome-equivalent. This test pins the warning-cardinality axis on the same race by adding the rule-3 regular-file replacement that drives the SPEC 7.4 warning-emitting cleanup branch. Set `NODE_ENV=test`, `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE=cleanup-start`, and `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE_MARKER=<absolute-path>`. Fixture `.loopx/ralph/index.sh` observes `LOOPX_TMPDIR` into an external marker, then performs the rule-3 regular-file replacement (`rm -rf "$LOOPX_TMPDIR" && printf '%s' "regular-file-replacement" > "$LOOPX_TMPDIR"` so the cleanup path emits a warning), writes `"ready"` to stderr, then sleeps 30 seconds (long-lived, ensures the loop body is still active when the harness fires `.return()`). Drive via `runAPIDriverLive()`: `const c = new AbortController(); const gen = run("ralph", { signal: c.signal });` Call `gen.next()` to enter the loop body and start the script. `await waitForStderr("ready")`. Call `gen.return(undefined)` — this is a mid-loop `.return()` (post-first-`next()`), not the pre-first-`next()` carve-out path. Loopx observes the `.return()` as the first-observed terminal trigger, terminates the active child process group (per SPEC 9.1 consumer-cancellation), and enters the cleanup routine. The seam pauses cleanup at start and writes the parent-observable marker. The harness polls for the marker, then calls `c.abort()` during the bounded pause (the racing post-`.return()` abort enumerated in SPEC 7.2). After loopx resumes and completes the single cleanup attempt, await the generator's settlement. Assert: (a) the generator settles **cleanly with the `.return()` value** (`{ done: true, value: undefined }`) — the `.return()` was observed first and per SPEC 7.2's first-observed-wins residual rule the post-pause abort does not displace the clean settlement (matching T-TERM-02 variant b's surfaced-outcome assertion on the warning-free counterpart); the settlement is **not** the abort error, (b) **stderr contains exactly one cleanup-related warning** (the rule-3 warning from the single cleanup attempt; no second cleanup attempt is started by the racing abort, so no second warning — the SPEC 7.2 "do not start a second cleanup attempt and do not re-emit cleanup warnings" contract holds on this observation order the same as on T-TMP-38a's inverted order), and (c) the regular-file replacement at the recorded tmpdir path still exists with content `regular-file-replacement` (cleanup completed once and left the rule-3 path in place per SPEC 7.4 rule-3; no double cleanup attempt). A buggy implementation that started a second cleanup attempt on the racing abort (e.g., one that correctly handled the abort-first × `.return()`-second race in T-TMP-38a but missed the inverted order where `.return()` initiates cleanup and abort races against an already-in-progress cleanup) would produce a second warning and fail (b); an implementation that surfaced the abort error here — displacing the first-observed `.return()` — would fail (a). Together with T-TMP-38a (abort-first × `.return()`-second), this closes the mid-loop `.return()` × abort race symmetrically across both observation orders on the warning-cardinality axis, completing the same symmetry that T-TMP-38c / T-TMP-38d2 close on the `.throw()` axis (mid-loop `.throw()` and post-final-yield `.throw()` respectively). `@flaky-retry(2)`. *(Spec 7.2, 7.4, 9.1)*
+- **T-TMP-38b**: Cleanup idempotence on the programmatic `runPromise()` surface — non-zero script exit observed first, racing abort during cleanup-start does not start a second cleanup attempt. Companion to T-TMP-38a covering the non-zero-exit-then-abort race on the `runPromise()` surface, matching SPEC 7.2's "non-zero exit concurrent with abort" enumeration. Set `NODE_ENV=test`, `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE=cleanup-start`, and `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE_MARKER=<absolute-path>`. Fixture `.loopx/ralph/index.sh` observes `LOOPX_TMPDIR` into an external marker, then performs the rule-3 regular-file replacement (warning-emitting branch), then exits 1. Drive via `runAPIDriverLive()`: `const c = new AbortController(); const p = runPromise("ralph", { signal: c.signal, maxIterations: 1 });` Loopx observes the script's non-zero exit first, dispatches the script-failure outcome, and enters the cleanup routine. The seam pauses cleanup-start and writes the marker. The harness polls for the marker, then calls `c.abort()` during the bounded pause. After loopx resumes, await `p`. Assert: (a) the promise rejects with the **non-zero-exit / script-failure error** (the first-observed trigger; the post-cleanup-start abort does not displace it), (b) **stderr contains exactly one cleanup-related warning** (the rule-3 warning from the single cleanup attempt), and (c) the regular-file replacement at the recorded tmpdir path still exists. A buggy implementation that started a second cleanup attempt on the racing abort would produce a second warning and fail (b); an implementation that surfaced an abort error would fail (a). Together with T-TMP-38a (abort-first × `.return()`-second), this closes the programmatic-surface idempotence contract on at least one of each "first-trigger" axis (abort-first and exit-first), satisfying SPEC 7.2's enumerated programmatic races. `@flaky-retry(2)`. *(Spec 7.2, 7.4, 9.1, 9.2)*
+- **T-TMP-38c**: Cleanup idempotence on the programmatic `run()` surface — abort observed first, racing `.throw()` during cleanup-start does not start a second cleanup attempt. Companion to T-TMP-38a (which covers the abort-first × `.return()`-second race) for the `.throw()` axis of SPEC 7.2's enumerated "abort concurrent with consumer `.return()` / `.throw()`" race. T-TMP-38a closes the `.return()` half; this test closes the `.throw()` half on the cleanup-idempotence axis. Together with T-TERM-02c / T-TERM-02d (which close the surfaced-outcome axis for the `.throw()` race) and T-TMP-38a / T-TMP-38b (which close the cleanup-idempotence axis for the `.return()` and non-zero-exit races), this closes the SPEC 7.2 cleanup-idempotence contract on the `.throw()` axis as well. Set `NODE_ENV=test`, `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE=cleanup-start`, and `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE_MARKER=<absolute-path>`. Fixture `.loopx/ralph/index.sh` observes `LOOPX_TMPDIR` into an external marker, then performs the rule-3 regular-file replacement (`rm -rf "$LOOPX_TMPDIR" && printf '%s' "regular-file-replacement" > "$LOOPX_TMPDIR"` so the cleanup path emits a warning), writes `"ready"` to stderr, then sleeps 30 seconds. Drive via `runAPIDriverLive()`: `const c = new AbortController(); const gen = run("ralph", { signal: c.signal });` Call `gen.next()` to enter the loop body. `await waitForStderr("ready")`. Call `c.abort()` — loopx observes the abort first, terminates the script (per SPEC 9.1 abort handling), and enters the cleanup routine. The seam pauses cleanup at start and writes the parent-observable marker. The harness polls for the marker, then calls `gen.throw(new Error("test-throw"))` during the bounded pause (this is a mid-loop `.throw()` racing with the in-progress cleanup). After loopx resumes, await the generator's settlement. Assert: (a) the generator settles by **throwing an abort error** (the first-observed trigger — SPEC 7.2 first-trigger-wins; the post-cleanup-start `.throw()` does not displace the abort outcome and the consumer-thrown `Error("test-throw")` does not appear in the rejection chain), (b) **stderr contains exactly one cleanup-related warning** (the rule-3 warning from the single cleanup attempt; no second cleanup attempt and therefore no second warning — the SPEC 7.2 / 7.4 idempotence contract holds across the `.throw()` race the same as across the `.return()` race), and (c) the regular-file replacement at the recorded tmpdir path still exists with content `regular-file-replacement` (cleanup completed once and left the rule-3 path in place; no double cleanup attempt). A buggy implementation that started a second cleanup attempt on the racing `.throw()` would produce a second warning and fail (b); an implementation that surfaced the consumer-thrown error or wrapped it around the abort would fail (a). `@flaky-retry(2)`. *(Spec 7.2, 7.4, 9.1)*
+- **T-TMP-38d**: Cleanup idempotence on the programmatic `run()` surface — **abort after final yield** (script-driven `stop: true`) observed first, racing `.throw()` during cleanup-start does not start a second cleanup attempt and emits at most one cleanup warning. SPEC 7.2 enumerates "abort after final yield concurrent with a consumer `.throw()`" as one of the explicit races for which idempotence and warning cardinality must hold. T-API-66b / T-API-66e cover the **outcome** axis of this race (post-final-yield `.throw()` rejects with the abort error, displacing the consumer-thrown error per SPEC 9.3's abort-after-final-yield rule), but their fixtures do not exercise a warning-emitting cleanup branch — the scripts terminate cleanly without mutating `$LOOPX_TMPDIR`, so cleanup runs without emitting any warning, and the assertion "exactly one cleanup warning" cannot distinguish single-cleanup-attempt from double-cleanup-attempt code paths. This test pins the warning-cardinality axis on the same race by adding the rule-3 regular-file replacement that drives the SPEC 7.4 warning-emitting cleanup branch. T-TMP-38c covers the **mid-loop** abort-`.throw()` race (script blocks and is interrupted); this test covers the **post-final-yield** abort-`.throw()` race (script completes via `stop: true`, then abort and `.throw()` race during cleanup) — a structurally distinct code path inside loopx because no active child needs to be terminated and SPEC 9.3's abort-after-final-yield precedence rule (rather than SPEC 9.1's mid-loop abort handling) drives the outcome. Set `NODE_ENV=test`, `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE=cleanup-start`, and `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE_MARKER=<absolute-path>`. Fixture `.loopx/ralph/index.sh` observes `LOOPX_TMPDIR` into a marker external to the tmpdir, performs the rule-3 regular-file replacement (`rm -rf "$LOOPX_TMPDIR" && printf '%s' "regular-file-replacement" > "$LOOPX_TMPDIR"` so the cleanup path emits a warning), then emits `{"stop":true}` and exits 0 (the final-yield trigger). Drive via `runAPIDriverLive()`: `const c = new AbortController(); const gen = run("ralph", { signal: c.signal, maxIterations: 5 });` Call `const first = await gen.next();` and verify `first.value.stop === true` (the script's `stop: true` makes this the final yield even though `maxIterations` permits more iterations — mirroring T-API-66c's `stop: true`-driven final-yield setup). Call `c.abort()` — loopx observes the abort after the final yield but before settlement; per SPEC 9.3 abort-after-final-yield, the abort displaces normal completion and loopx enters the cleanup routine. The seam pauses cleanup at start and writes the parent-observable marker. The harness polls for the marker, then calls `gen.throw(new Error("test-throw"))` during the bounded pause (the racing post-final-yield consumer `.throw()` enumerated in SPEC 7.2). After loopx resumes, await the generator's settlement. Assert: (a) the generator settles by **throwing the abort error** (the abort was observed first and SPEC 9.3's abort-after-final-yield rule pins the outcome; the post-cleanup-start `.throw()` does not displace it and the consumer-thrown `Error("test-throw")` does not appear in the rejection chain — equivalent contract to T-API-66b / T-API-66e but driven through the cleanup-pause race rather than direct interaction sequencing), (b) **stderr contains exactly one cleanup-related warning** (the rule-3 warning from the single cleanup attempt; no second cleanup attempt is started by the racing `.throw()`, so no second warning — the SPEC 7.2 "do not start a second cleanup attempt and do not re-emit cleanup warnings" contract holds on the post-final-yield `.throw()` race the same as on the mid-loop `.throw()` race covered by T-TMP-38c), and (c) the regular-file replacement at the recorded tmpdir path still exists with content `regular-file-replacement` (cleanup completed once and left the rule-3 path in place per SPEC 7.4 rule-3; no double cleanup attempt). A buggy implementation that started a second cleanup attempt on the racing `.throw()` (e.g., one that correctly handled the mid-loop race in T-TMP-38c via a "is the script still running?" gate but missed the post-final-yield branch where the script is already gone) would produce a second warning and fail (b); an implementation that surfaced the consumer-thrown error in this race would fail (a). `@flaky-retry(2)`. *(Spec 7.2, 7.4, 9.3)*
+- **T-TMP-38d2**: Cleanup idempotence on the programmatic `run()` surface — **post-final-yield consumer `.throw()`** observed first, racing abort during cleanup-start does not start a second cleanup attempt and emits at most one cleanup warning. Symmetric counterpart to T-TMP-38d for the `.throw()`-first × abort-second observation order on the post-final-yield race surface; closes the matrix-symmetry gap for SPEC 7.2's "abort after final yield concurrent with consumer `.throw()`" enumeration on the warning-cardinality axis. T-TMP-38d covers the abort-first × `.throw()`-second order (where SPEC 9.3's abort-after-final-yield rule pins the surfaced outcome to the abort error); this test covers the inverted order, where `.throw()` is observed first and the post-pause abort races against an already-in-progress cleanup; only the cleanup-idempotence and warning-cardinality axes — the parts SPEC §7.2 unambiguously enumerates as holding on this race — are pinned here, since the surfaced-outcome axis on this observation order is recorded as ambiguous in `SPEC-PROBLEMS.md` § P-0004-01 (SPEC §9.3 vs. §7.2 / §9.1 admit two readings in opposite directions). Set `NODE_ENV=test`, `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE=cleanup-start`, and `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE_MARKER=<absolute-path>`. Fixture `.loopx/ralph/index.sh` observes `LOOPX_TMPDIR` into a marker external to the tmpdir, performs the rule-3 regular-file replacement (`rm -rf "$LOOPX_TMPDIR" && printf '%s' "regular-file-replacement" > "$LOOPX_TMPDIR"` so the cleanup path emits a warning), then emits `{"stop":true}` and exits 0 (the final-yield trigger). Drive via `runAPIDriverLive()`: `const c = new AbortController(); const gen = run("ralph", { signal: c.signal, maxIterations: 5 });` Call `const first = await gen.next();` and verify `first.value.stop === true` (the script's `stop: true` makes this the final yield even though `maxIterations` permits more iterations — mirroring T-TMP-38d's `stop: true`-driven final-yield setup). Call `gen.throw(new Error("test-throw"))` — this is the first-observed terminal trigger after final yield (per SPEC 7.4's "Consumer-driven cancellation ... `.throw()` after first `next()`" cleanup trigger; the script has already exited, so the no-active-child branch of SPEC 9.1 applies). Loopx records the `.throw()` as first-observed and enters the cleanup routine. The seam pauses cleanup at start and writes the parent-observable marker. The harness polls for the marker, then calls `c.abort()` during the bounded pause (the racing post-final-yield abort enumerated in SPEC 7.2 — but in inverted observation order from T-TMP-38d). After loopx resumes and completes the single cleanup attempt, await the generator's settlement. **Surfaced-outcome axis is observational, not asserted.** Per `SPEC-PROBLEMS.md` § P-0004-01, SPEC §9.3 ("the abort produces the abort error on the next generator interaction — `g.next()`, `.return()`, or `.throw()`") and SPEC §7.2 / §9.1 (first-observed-wins residual rule combined with the no-active-child silent-clean-completion rule for consumer cancellation) admit two readings of this race in opposite directions: ADR-0004's "abort still wins until generator settlement" supports an abort-wins reading even when consumer `.throw()` was observed first, while §7.2's first-observed-wins residual rule supports a `.throw()`-wins reading once the consumer interaction has already entered cleanup. Until SPEC clarifies, this test pins only the cleanup-idempotence and warning-cardinality axes that SPEC §7.2 *does* unambiguously enumerate as holding on this race ("abort after final yield concurrent with a consumer `.throw()` ... do not start a second cleanup attempt and do not re-emit cleanup warnings"); the harness may record the surfaced settlement outcome (clean `{ done: true }` / abort-error rejection / consumer-thrown rejection) for diagnostic purposes, but the test does not assert which outcome appears. Assert: (a) **stderr contains exactly one cleanup-related warning** (the rule-3 warning from the single cleanup attempt; no second cleanup attempt is started by the racing abort, so no second warning — the SPEC 7.2 "do not start a second cleanup attempt and do not re-emit cleanup warnings" contract holds on this observation order the same as on T-TMP-38d's inverted order), and (b) the regular-file replacement at the recorded tmpdir path still exists with content `regular-file-replacement` (cleanup completed once and left the rule-3 path in place per SPEC 7.4 rule-3; no double cleanup attempt). A buggy implementation that started a second cleanup attempt on the racing abort (e.g., one that correctly handled the abort-first × `.throw()`-second race in T-TMP-38d but missed the inverted order where `.throw()` initiates cleanup and abort races against an already-in-progress cleanup) would produce a second warning and fail (a), and would also re-touch the rule-3 entry on the second attempt — corrupting or removing it and failing (b). The surfaced-outcome assertion that previously appeared here has been removed pending SPEC clarification (P-0004-01). Together with T-TMP-38d (abort-first × `.throw()`-second, post-final-yield), this closes the post-final-yield abort × `.throw()` race symmetrically across both observation orders on the warning-cardinality axis, mirroring the surfaced-outcome axis closed by T-API-66b / T-API-66e (abort-first) and T-TMP-22d / T-TMP-22f (`.throw()`-first, post-final-yield, no-abort-race). `@flaky-retry(2)`. *(Spec 7.2, 7.4, 9.1, 9.3)*
+- **T-TMP-38e**: Cleanup idempotence on the programmatic `runPromise()` surface — **child spawn failure concurrent with abort** does not start a second cleanup attempt and emits at most one cleanup warning. **Parameterize over both observation orders** (mirroring T-TERM-04's variant structure). SPEC 7.2 enumerates "child spawn failure concurrent with abort" as one of the explicit races for which idempotence and warning cardinality must hold. T-TERM-04 covers the **outcome** axis of this race (first-observed-trigger wins) for both observation orders, but its fixture does not exercise a warning-emitting cleanup branch — the loopx-created tmpdir is empty (no script ran to mutate it), so cleanup takes the rule-4 identity-matched-directory branch and completes without warning, and the assertion "exactly one cleanup warning" cannot distinguish single-cleanup-attempt from double-cleanup-attempt code paths. This test pins the warning-cardinality axis on the same race by adding `LOOPX_TEST_CLEANUP_FAULT=recursive-remove-fail` (per the section 1.4 seam contract) to make rule-4 cleanup emit the SPEC 7.4 warning. The race is structurally important because both spawn-failure and abort independently drive cleanup (per SPEC 7.4's cleanup-triggers list), and a naïve implementation that wired separate cleanup-dispatchers into the spawn-failure callback and the abort listener could plausibly start two cleanup attempts and emit two warnings without violating any outcome-axis assertion in T-TERM-04. **Tmpdir-path observation (both variants).** Because the embedded-NUL fixture causes spawn rejection before any child is launched, no script runs and no script can write `LOOPX_TMPDIR` to a marker file. The harness instead obtains the recorded tmpdir path by **scanning the test-isolated `TMPDIR` parent for the single `loopx-*` entry** that `LOOPX_TEST_CLEANUP_FAULT=recursive-remove-fail` leaves behind after rule-4 cleanup emits the SPEC 7.4 warning and stops without removing the path: per the section 4.7 preface every test runs under a freshly-allocated test-isolated `TMPDIR`, so the loopx-created tmpdir is the **only** `loopx-*` entry under that parent at post-run inspection time. The harness reads the parent (e.g., `fs.readdirSync(testTmpdirParent).filter(name => name.startsWith("loopx-"))`), asserts that **exactly one** entry matches (a defensive check against any stray entries the seam might create), and uses that single entry's absolute path as the "recorded tmpdir path" for assertion (c) below. After all assertions complete, the harness teardown removes that entry along with the rest of the test-isolated `TMPDIR` parent per the standard fixture-cleanup pattern. **Variant a (spawn-failure observed first, abort racing during cleanup):** Set `NODE_ENV=test`, `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE=child-spawn-failure`, `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE_MARKER=<absolute-path>`, and `LOOPX_TEST_CLEANUP_FAULT=recursive-remove-fail`. Drive via `runAPIDriverLive()`: `const c = new AbortController(); const p = runPromise("ralph", { signal: c.signal, env: { MYVAR: "bad\0val" }, maxIterations: 1 });` (the embedded-NUL value drives the runtime to reject the spawn at child launch time per SPEC 7.2 / 9.5 / T-API-57 / T-TERM-04 — the same spawn-rejection pathway used by T-TERM-04 variant a). Loopx attempts the spawn, the runtime rejects the env entry, loopx observes the spawn-failure trigger, the seam writes the marker and pauses at the post-observation point. The harness polls for the marker, then calls `c.abort()` during the bounded pause (the racing abort enumerated in SPEC 7.2). After loopx resumes, await `p`. Assert: (a) the promise rejects with the **spawn-failure error** (the first-observed trigger per T-TERM-04 variant a; the post-pause abort does not displace it), (b) **stderr contains exactly one cleanup-related warning** — the rule-4 warning from the single cleanup attempt against the loopx-created tmpdir (with `LOOPX_TEST_CLEANUP_FAULT=recursive-remove-fail`, the rule-4 branch emits the SPEC 7.4 warning); no second cleanup attempt is started by the racing abort, so no second warning, and (c) the recorded tmpdir path still exists on disk (per SPEC 7.4 "no further changes" after the rule-4 warning is emitted). **Variant b (abort observed first, spawn-failure racing on resume):** Set `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE=child-spawn-attempt` and `LOOPX_TEST_CLEANUP_FAULT=recursive-remove-fail`. Same NUL-in-env fixture. Drive via `runAPIDriverLive()` with the same arguments. Loopx enters the spawn-attempt path and pauses at the `child-spawn-attempt` seam **before** observing the spawn outcome (the seam is essential here per T-TERM-04's variant-b rationale — without it, an abort delivered before the spawn attempt begins pre-empts the spawn entirely under "abort wins over pre-iteration failures" and never reaches the genuine race). The seam writes the marker. The harness polls, then calls `c.abort()` during the pause (loopx's abort listener observes the abort while the spawn attempt is paused). On resume, loopx observes the spawn failure later. Assert: (a) the promise rejects with the **abort error** (first-observed per T-TERM-04 variant b; the spawn-failure on resume does not displace it), (b) **stderr contains exactly one cleanup-related warning** — same single-attempt rule-4 warning as variant a; no second cleanup attempt is started by the spawn-failure that arrives after the abort-driven cleanup is in progress, and (c) the recorded tmpdir path still exists on disk. A buggy implementation that started a second cleanup attempt on the racing trigger (in either variant) would produce a second warning and fail (b); an implementation that surfaced the wrong outcome would fail (a) — but the (a) failure mode is already covered by T-TERM-04, so the load-bearing assertion in this test is (b) on the warning-cardinality axis. `@flaky-retry(2)` for both variants. *(Spec 7.2, 7.4, 9.3, 9.5)*
+- **T-TMP-38f**: Cleanup idempotence under racing **SIGTERM → SIGINT** (inverted-order parity for T-TMP-38). SPEC 7.2's first-observed-trigger-wins rule and SPEC 7.4's at-most-one-cleanup-attempt / at-most-one-cleanup-warning rules apply symmetrically across SIGINT and SIGTERM — neither signal is privileged. T-TMP-38 covers the SIGINT-first × SIGTERM-second-during-cleanup race; T-TMP-39 covers the same SIGINT-first race on the rule-5 mismatched-directory warning branch; T-TERM-03 covers the same SIGINT-first race on the surfaced-exit-code axis. None of those exercises the inverted observation order. A buggy implementation that special-cased SIGINT-first cleanup-race handling (e.g., a SIGINT-handler path that correctly gated cleanup-idempotence and exit-code precedence, but a SIGTERM-handler path that re-entered cleanup or surfaced the second signal's exit code) would pass T-TMP-38 / T-TMP-39 / T-TERM-03 yet fail this test. Same fixture and seam configuration as T-TMP-38: set `NODE_ENV=test`, `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE=cleanup-start`, and `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE_MARKER=<absolute-path>`. Fixture `.loopx/ralph/index.sh` observes `LOOPX_TMPDIR` into a marker external to the tmpdir, then renames it aside and creates a regular-file replacement (`rm -rf "$LOOPX_TMPDIR" && printf '%s' "regular-file-replacement" > "$LOOPX_TMPDIR"` — the rule-3 cleanup-warning-emitting branch from T-TMP-35), writes `"ready"` to stderr, then blocks indefinitely. Run via `runCLIWithSignal`. Wait for `"ready"` on stderr, then send **SIGTERM** to loopx (the *first*-observed signal in the inverted order); the SIGTERM triggers the terminal cleanup path. The seam pauses loopx at cleanup start and writes the parent-observable marker. The harness polls for the marker file, then sends **SIGINT** to loopx during the bounded pause (the *second* signal in the inverted order). After the pause resumes, loopx completes cleanup. Assert: (a) loopx exits with the SIGTERM exit code **143** (the first-observed signal — SPEC 7.2 first-trigger-wins applied symmetrically to SIGTERM; the post-cleanup-start SIGINT does **not** displace the first signal's exit code, and the surfaced exit code is **not** 130), (b) **stderr contains exactly one cleanup-related warning** (the rule-3 warning was emitted during the single cleanup attempt; no second cleanup attempt and therefore no second warning — the SPEC 7.2 / 7.4 idempotence contract holds symmetrically across SIGTERM-first and SIGINT-first observation orders), and (c) the regular-file replacement at the recorded tmpdir path still exists with content `regular-file-replacement` (cleanup completed once, leaving the rule-3 path in place, with no double-cleanup attempt). A buggy implementation that started a second cleanup attempt on the second signal would produce a second cleanup-related warning and fail (b); an implementation whose racing-trigger logic was conditioned on the first signal being SIGINT specifically would surface the second-signal SIGINT's exit code 130 (rather than the first-signal SIGTERM's 143) and fail (a). Together with T-TMP-38 (SIGINT-first × SIGTERM-second), this closes the racing-signal idempotence contract symmetrically across both observation orders, matching the SPEC 7.2 / 7.4 normative SIGINT/SIGTERM symmetry. `@flaky-retry(2)`. *(Spec 7.2, 7.3, 7.4)*
+
+##### Terminal-Outcome Precedence Across Genuinely Racing Triggers
+
+SPEC 7.2 ("Terminal-outcome precedence") specifies that, except where an explicit precedence rule applies, the **first terminal trigger observed by loopx determines the surfaced outcome among genuinely racing triggers** — "observed by loopx" being the point at which the trigger enters loopx's own tracking (signal handler, abort listener, child-exit callback, consumer interaction), not OS-level delivery order. Test coverage exists for the **explicit precedence rules**: the pre-first-`next()` consumer-cancellation carve-out (T-API-09d / T-API-09e), the abort-wins-over-pre-iteration-failures rule (T-API-65–65o), the CLI pre-iteration signal-wins rule (T-SIG-20–28), and the abort-after-final-yield rule (T-API-65n / counterparts). The residual rule — **first-observed wins among genuinely racing triggers** — is covered by T-TERM-01..T-TERM-04 deterministically via the section 1.4 `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE` seam. The seam pauses loopx **after** loopx has recorded the first-observed trigger but **before** outcome dispatch, allowing the harness to fire a competing second trigger during the pause; on resume, the surfaced outcome must reflect the first-observed (pre-pause) trigger, not the second (post-pause) trigger.
+
+- **T-TERM-01**: Racing non-zero exit vs. abort — surfaced outcome reflects the first-observed trigger. **Parameterize over both observation orders.** **Variant a (child-exit observed first):** Set `NODE_ENV=test`, `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE=child-exit-handler`, and `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE_MARKER=<absolute-path>`. Fixture `.loopx/ralph/index.sh` exits 1 immediately. Drive via `runAPIDriverLive()`: `const c = new AbortController(); const p = runPromise("ralph", { signal: c.signal, maxIterations: 1 });` The driver's child observes the `exit 1` and writes the pause marker. The harness polls for the marker, then calls `c.abort()` during the bounded pause. After loopx resumes, await `p`. Assert: (a) the promise rejects with the **non-zero-exit / script-failure error** — the child-exit was the first-observed trigger and dispatches first, the post-pause abort does not displace it, and (b) no abort error appears in the rejection (not chained, not wrapped). **Variant b (abort observed first):** Set `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE=abort-listener`. Fixture `.loopx/ralph/index.sh` writes `"ready"` to stderr and then sleeps 30 seconds (long-lived). Drive via `runAPIDriverLive()`: `const c = new AbortController(); const p = runPromise("ralph", { signal: c.signal, maxIterations: 1 });` `await waitForStderr("ready")`. Call `c.abort()` to fire the abort. Loopx observes the abort and writes the pause marker. The harness polls for the marker, then signals the script's process group to force a non-zero exit (the harness has the script's PID via the `runAPIDriverLive` driver-process channel, or alternatively delivers SIGKILL via `process.kill(-childPgid, "SIGKILL")` to make the script exit non-zero during the pause). After loopx resumes, await `p`. Assert: (a) the promise rejects with the **abort error** (the abort was observed first), and (b) no script-failure error displaces it. Together, the two variants prove the surfaced outcome reflects the first-observed trigger regardless of which trigger is which. `@flaky-retry(2)`. *(Spec 7.2)*
+- **T-TERM-02**: Racing abort vs. consumer `.return()` — surfaced outcome reflects the first-observed trigger. **Parameterize over both observation orders.** **Variant a (abort observed first):** Set `NODE_ENV=test`, `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE=abort-listener`, and `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE_MARKER=<absolute-path>`. Fixture `.loopx/ralph/index.sh` writes `"ready"` to stderr and sleeps 30 seconds. Drive via `runAPIDriverLive()`: `const c = new AbortController(); const gen = run("ralph", { signal: c.signal });` Call `gen.next()` to enter the loop body and start the script. `await waitForStderr("ready")`. Call `c.abort()`. Loopx observes the abort and writes the pause marker. The harness polls for the marker, then calls `gen.return(undefined)` during the pause. After loopx resumes and the generator settles, await the resolution. Assert: the generator settles by **throwing an abort error** (the abort was observed first; the post-pause `.return()` does not produce a clean settlement). **Variant b (`.return()` observed first):** Set `NODE_ENV=test`, `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE=consumer-return-observed`, and `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE_MARKER=<absolute-path>`. Fixture `.loopx/ralph/index.sh` writes `"ready"` to stderr and sleeps 30 seconds (long-lived, ensures the loop body is still active when the harness fires `.return()`). Drive via `runAPIDriverLive()`: `const c = new AbortController(); const gen = run("ralph", { signal: c.signal });` Call `gen.next()` to enter the loop body and start the script. `await waitForStderr("ready")`. Call `gen.return(undefined)` — this is a mid-loop `.return()` (post-first-`next()`), not the pre-first-`next()` carve-out path. Loopx observes the `.return()` trigger and writes the pause marker. The harness polls for the marker, then calls `c.abort()` during the bounded pause. After loopx resumes and the generator settles, await the resolution. Assert: the generator settles **cleanly** with the `.return()` value (per standard async-generator `.return()` semantics — first-observed trigger wins, the post-pause abort does not displace the clean settlement). Together, the two variants prove the surfaced outcome reflects the first-observed trigger regardless of which trigger is which. `@flaky-retry(2)`. *(Spec 7.2, 9.1)*
+- **T-TERM-02c**: Racing abort vs. consumer `.throw()` — abort observed first wins. SPEC 7.2's terminal-outcome precedence enumerates "abort concurrent with consumer `.return()` / `.throw()`" as a covered race; T-TERM-02 variants a/b close the `.return()` axis, and this test closes the abort-first × `.throw()`-second branch of the `.throw()` axis. The `consumer-throw-observed` pause-seam window value is declared in section 1.4 alongside `consumer-return-observed` precisely so this race can be pinned deterministically. Set `NODE_ENV=test`, `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE=abort-listener`, and `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE_MARKER=<absolute-path>`. Fixture `.loopx/ralph/index.sh` writes `"ready"` to stderr and sleeps 30 seconds. Drive via `runAPIDriverLive()`: `const c = new AbortController(); const gen = run("ralph", { signal: c.signal });` Call `gen.next()` to enter the loop body and start the script. `await waitForStderr("ready")`. Call `c.abort()`. Loopx observes the abort, writes the pause marker, and pauses at the abort-listener post-observation window. The harness polls for the marker, then calls `gen.throw(new Error("test-throw"))` during the bounded pause. After loopx resumes and the generator settles, await the resolution. Assert: the generator settles by **throwing an abort error** (the abort was observed first — SPEC 7.2 first-trigger-wins; the post-pause `.throw()` does not displace the abort outcome), and the rejection reason is the abort error rather than the `Error("test-throw")` consumer-thrown value (the late-arriving `.throw()` neither chains, wraps, nor replaces the abort). A buggy implementation that surfaced the consumer-thrown error in this race window — even after correctly handling the abort-first × `.return()` race in T-TERM-02 variant a — would fail. `@flaky-retry(2)`. *(Spec 7.2, 9.1)*
+- **T-TERM-02d**: Racing consumer `.throw()` vs. abort — `.throw()` observed first, surfaced outcome is **not abort**. SPEC 7.2's "first terminal trigger observed by loopx determines the surfaced outcome among genuinely racing triggers" rule means a `.throw()` observed first must drive the surfaced outcome regardless of a competing post-pause abort. SPEC 9.1 does not pin the exact settlement shape of a mid-loop `.throw()` — implementations may surface the consumer-thrown error directly, may wrap it with implementation-defined cleanup-failure metadata, or (consistent with standard JS async-generator `.throw()` semantics) may complete cleanly when the loop body has already started shutting down before the throw is delivered. Because that exact shape is implementation-defined, this test asserts the SPEC-required negative — the surfaced outcome is **not** the abort error and is not displaced by the post-pause abort — plus the SPEC-required cleanup invariants (cleanup ran, single warning if any, tmpdir handled per the cleanup-safety rules). Set `NODE_ENV=test`, `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE=consumer-throw-observed`, and `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE_MARKER=<absolute-path>`. Fixture `.loopx/ralph/index.sh` observes `LOOPX_TMPDIR` into a marker external to the tmpdir, writes `"ready"` to stderr, and sleeps 30 seconds (long-lived, ensures the loop body is still active when the harness fires `.throw()`). Drive via `runAPIDriverLive()`: `const c = new AbortController(); const gen = run("ralph", { signal: c.signal });` Call `gen.next()` to enter the loop body and start the script. `await waitForStderr("ready")`. Call `gen.throw(new Error("test-throw"))` — this is a mid-loop `.throw()` (post-first-`next()`), not the pre-first-`next()` carve-out path. Loopx observes the `.throw()` trigger and writes the pause marker. The harness polls for the marker, then calls `c.abort()` during the bounded pause. After loopx resumes and the generator settles, await the resolution. Assert: (a) the generator settlement is **not the abort error** (the surfaced outcome — whether a clean completion or a consumer-thrown rejection — is whatever the implementation deterministically produces for a mid-loop `.throw()` first-observed trigger; SPEC 7.2 guarantees only that the post-pause abort does not displace it), (b) the recorded `LOOPX_TMPDIR` path no longer exists on disk (cleanup ran exactly once before the generator settled — SPEC 7.4 settlement-precedes-rejection contract), and (c) stderr contains at most one cleanup-related warning (SPEC 7.4 warning cardinality). The test is robust to either consumer-thrown-error or clean-completion settlement shapes; an implementation that surfaced the abort error here — displacing the first-observed `.throw()` — would fail (a). `@flaky-retry(2)`. *(Spec 7.2, 9.1)*
+- **T-TERM-03**: Racing signal during cleanup vs. cleanup completion — surfaced outcome reflects the first-observed signal. Set `NODE_ENV=test`, `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE=cleanup-start`, and `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE_MARKER=<absolute-path>`. Fixture `.loopx/ralph/index.sh` observes `LOOPX_TMPDIR` into an external marker, writes `"ready"` to stderr, then blocks indefinitely. Run via `runCLIWithSignal`. Wait for `"ready"`, then send **SIGINT** to loopx (the first-observed signal). Loopx forwards the signal to the script's process group, the script dies, and loopx enters the cleanup routine. The seam pauses loopx at cleanup-start and writes the marker. The harness polls for the marker, then sends **SIGTERM** to loopx during the bounded pause. After loopx resumes and completes cleanup, the process exits. Assert: (a) loopx exits with code **130** (SIGINT — the first-observed signal), **not** 143 (SIGTERM — the second signal received during the post-cleanup-start pause), (b) cleanup completed (the recorded tmpdir path no longer exists on disk — successful cleanup ran exactly once), and (c) stderr contains no cleanup-related warning (cleanup ran successfully without warning, matching T-TMP-13's clean-cleanup contract). T-TMP-38 covers the cleanup-idempotence angle (at-most-one cleanup attempt, at-most-one warning); this test pins the surfaced-exit-code angle separately. Together they close the racing-signal-during-cleanup contract across both axes (idempotence and outcome-precedence). `@flaky-retry(2)`. *(Spec 7.2, 7.4)*
+- **T-TERM-04**: Racing child spawn failure vs. abort — surfaced outcome reflects the first-observed trigger. **Parameterize over both observation orders.** **Variant a (spawn-failure observed first):** Set `NODE_ENV=test`, `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE=child-spawn-failure`, and `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE_MARKER=<absolute-path>`. Configure the project to deterministically fail child spawn on first iteration via a runtime-rejected env entry — `runPromise("ralph", { signal: c.signal, env: { MYVAR: "bad\0val" }, maxIterations: 1 })` — matching the SPEC 7.2 / 9.5 / T-API-57 spawn-failure pathway (an embedded-NUL value in `RunOptions.env` that the runtime rejects at child launch time). This produces a reliable spawn-path failure on every supported runtime, unlike mode-000 / non-script-extension fixtures: a Bash script with mode `000` typically launches `/bin/bash` successfully and then exits non-zero when Bash cannot read the script, which is a script-exit path (handled by `child-exit-handler`), not a spawn-rejection path; the embedded-NUL env entry is rejected by the runtime's environment-building layer **before** any child binary is launched, so it surfaces as a true `spawn` rejection observable on the spawn-rejection callback. Drive via `runAPIDriverLive()`: `const c = new AbortController(); const p = runPromise("ralph", { signal: c.signal, env: { MYVAR: "bad\0val" }, maxIterations: 1 });` Loopx attempts the spawn, the runtime rejects the NUL-in-value env entry, and loopx observes the spawn-failure trigger. The seam pauses at the post-observation point and writes the marker. The harness polls for the marker, then calls `c.abort()` during the bounded pause. After resume, await `p`. Assert: (a) the promise rejects with the **spawn-failure error** (the first-observed trigger), (b) no abort error displaces it (not chained, not wrapped). **Variant b (abort observed first):** Set `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE=child-spawn-attempt`. Same NUL-in-env fixture (spawn-rejecting target). Drive via `runAPIDriverLive()`: `const c = new AbortController(); const p = runPromise("ralph", { signal: c.signal, env: { MYVAR: "bad\0val" }, maxIterations: 1 });` Loopx enters the spawn-attempt path and pauses at the `child-spawn-attempt` seam **before** observing the spawn outcome. The seam writes the marker. The harness polls for the marker, then calls `c.abort()` during the bounded pause. Loopx's abort listener observes the abort while the spawn attempt is paused; on resume, loopx observes the spawn-failure later. The surfaced outcome must reflect the abort (first-observed). Assert: (a) the promise rejects with the **abort error** (first-observed), (b) no spawn-failure error displaces it. The `child-spawn-attempt` seam (declared in section 1.4) is essential here: without it, an abort delivered before the spawn attempt begins pre-empts the spawn entirely under the explicit "abort wins over pre-iteration failures" rule (covered by T-API-65–65o), which is structurally distinct from the residual "first-observed wins among genuinely racing triggers" rule under test in this variant. With the seam, loopx is guaranteed to be inside the spawn-attempt window when abort is observed, so the spawn failure is genuinely racing rather than pre-empted. `@flaky-retry(2)` for both variants. *(Spec 7.2, 9.5)*
+
+##### Operational / Privilege-Dependent Tmpdir Clauses (Not Directly Covered)
+
+- **T-TMP-43 (not yet directly covered)**: Mount-point non-detection inside `$LOOPX_TMPDIR`. SPEC 7.4 says loopx does not detect or avoid mount points inside the tmpdir, but exercising this deterministically requires privileged mount operations that are unavailable in standard CI environments and not appropriate for the default test harness. This remains an explicit known gap unless a mount-capable integration environment is added.
+- **T-TMP-44 (not directly covered)**: Cleanup does not run on host crash / power loss. SPEC 7.4 says "Cleanup does **not** run when loopx itself is killed via SIGKILL or the host crashes". The SIGKILL branch is covered directly by T-TMP-24b (external SIGKILL to loopx); the host-crash / power-loss branch is not practically reproducible in CI. Inducing a real host crash would require privileged operations on the test machine (e.g., `echo c > /proc/sysrq-trigger`, `sync && halt -f`, or VM-level power-off) that are unavailable in standard CI and would terminate the test runner itself before any assertions could be observed. This branch is documented in SPEC 7.4 as a contract on what loopx **does not** guarantee, and the practical observable consequence is the same as SIGKILL (a leaked tmpdir reaped by OS temp-cleaning policy). This remains an explicit known gap; no executable test is required for SPEC-conformance coverage.
+
+##### `LOOPX_TMPDIR` Protocol-Variable Precedence
+
+Spec 8.3 makes `LOOPX_TMPDIR` a **script-protocol-protected variable** that must override user-supplied values from every lower tier. These tests complete the precedence-coverage pattern established by `LOOPX_BIN` / `LOOPX_PROJECT_ROOT` / `LOOPX_WORKFLOW` / `LOOPX_WORKFLOW_DIR` (T-ENV-20b / T-ENV-21a–21d / T-WFDIR-06–08), which each have symmetric inherited-env and env-file precedence tests. Without these, a buggy implementation could special-case `LOOPX_TMPDIR` to be read from inherited env or an env file instead of freshly injected from its own tmpdir-creation step.
+
+- **T-TMP-30**: `LOOPX_TMPDIR` overrides inherited-env values of the same name. Spawn loopx with `LOOPX_TMPDIR=/tmp/fake-loopx-tmp` in the inherited process environment. The fixture script observes `LOOPX_TMPDIR` via `observe-env` **and** performs an in-script `stat` of the observed `$LOOPX_TMPDIR` path **during execution** (before the script exits), recording the stat result (exists, is-a-directory) to a marker. The during-run stat is essential because SPEC 7.4 cleanup removes the tmpdir on run completion; a post-run stat would observe absence. Assert: (a) the observed marker records the real injected tmpdir path (under `os.tmpdir()` or the test-isolated parent, matching the `loopx-*` naming pattern), **not** `/tmp/fake-loopx-tmp`, (b) the during-run stat marker records "exists as a directory" — proving it is the real loopx-created tmpdir, not merely a substitution. Protocol variables win at tier 1 (SPEC 8.3). This is the `LOOPX_TMPDIR` counterpart to T-WFDIR-06 (`LOOPX_WORKFLOW_DIR` override) and T-ENV-21a (`LOOPX_PROJECT_ROOT` override). *(Spec 8.3, 7.4)*
+- **T-TMP-31**: `LOOPX_TMPDIR` overrides local env file (`-e`) value. Create a local env file containing `LOOPX_TMPDIR=/tmp/fake-loopx-tmp`. Run `loopx run -e <envfile> -n 1 ralph`. Script observes `LOOPX_TMPDIR`. Assert the marker contains the real injected tmpdir path, not `/tmp/fake-loopx-tmp`. This is the `-e` local env-file counterpart to T-TMP-30. Completes the SPEC 8.3 precedence coverage for `LOOPX_TMPDIR` alongside the inherited-env tier (T-TMP-30) and the global env-file tier (which loopx treats identically to the local `-e` tier for protocol-variable override — any env-file value is below the tier-1 protocol injection). Mirrors T-WFDIR-07 (`LOOPX_WORKFLOW_DIR` vs `-e`) and T-ENV-21c (`LOOPX_WORKFLOW` vs `-e`). *(Spec 8.3, 7.4)*
+
+#### `PWD` Non-Protocol Behavior
+
+Spec 6.1 / 8.3 / 13 explicitly declare `PWD` to be **outside** the script-protocol-protected tier. These tests pin down that `PWD` is not reserved or protected by loopx.
+
+**Fixture note.** Exact-value `PWD` passthrough assertions use a **TS fixture reading `process.env.PWD`** (via the existing `observe-env` fixture with variable name `PWD`), not Bash `$PWD`. Per SPEC 6.1 / 8.3 / 13, Bash `$PWD` is shell-maintained and subject to normal POSIX / Bash semantics — Bash may rewrite `$PWD` during shell startup, so exact byte-for-byte equality between Bash `$PWD` and a caller-supplied value is not a loopx guarantee. The TS `observe-env` fixture reads `process.env.PWD` directly via Node / Bun's env-map accessor, which preserves the inherited value byte-for-byte and does not apply shell-level PWD semantics. The Bash `observe-pwd` fixture is retained only for tests that specifically want to observe Bash's shell-managed `$PWD` variable (none of the T-PWD-* exact-value tests below).
+
+- **T-PWD-01**: loopx does not reserve/protect `PWD`. TS script observes `PWD` via `observe-env` (reading `process.env.PWD` directly, not Bash `$PWD` — see fixture note above). Spawn loopx with a specific `PWD=/some/inherited/value` in the inherited environment (using `execa`'s `env` option). Assert the marker records `{ "present": true, "value": "/some/inherited/value" }` — loopx did not unset, override, or rewrite `PWD`. Using `process.env.PWD` (not Bash `$PWD`) ensures the assertion is against the byte-for-byte inherited value rather than Bash's shell-level POSIX rewrite. *(Spec 6.1, 8.3, 13)*
+- **T-PWD-02**: `RunOptions.env.PWD` reaches spawned scripts. Call `runPromise("ralph", { env: { PWD: "/value-from-run-options" } })`. TS script observes `PWD` via `observe-env`. Assert marker records `{ "present": true, "value": "/value-from-run-options" }` — `RunOptions.env` (tier 2, Spec 8.3) supplies `PWD` unchanged because `PWD` is not at tier 1. The TS fixture is used so the assertion is against the env-map value, bypassing Bash's shell-level PWD rewrite. *(Spec 6.1, 8.3, 9.5)*
+- **T-PWD-03**: Inherited `PWD` propagates unchanged when neither env file nor `RunOptions.env` sets it. Spawn with `PWD=/inherited`. TS script observes `PWD` via `observe-env`. Assert marker records `{ "present": true, "value": "/inherited" }`. TS fixture used for the same reason as T-PWD-01/02. *(Spec 6.1, 8.3)*
+- **T-PWD-04**: Protocol variables (Spec 8.3 table) do **not** include `PWD`. A TS script enumerates `process.env` and writes the keys as JSON via `fs.writeFileSync`. Assert: (a) `LOOPX_BIN`, `LOOPX_PROJECT_ROOT`, `LOOPX_WORKFLOW`, `LOOPX_WORKFLOW_DIR`, and `LOOPX_TMPDIR` are all present; (b) `PWD` is either present (with the inherited value) or absent (if not in the loopx parent's env) — it is not forcibly injected. More importantly: when loopx is spawned without `PWD` in its own environment (e.g., `env -i node cli.js run ralph`), the script's `PWD` must **not** be present — proving loopx does not synthesize a `PWD` value when none is inherited. *(Spec 6.1, 8.3, 13)*
+- **T-PWD-05 (non-normative)**: *This item is a non-normative reminder, not an executable test.* Run help (Spec 11.2) does not currently document protocol variables, so a literal "`PWD` must not appear in `loopx run -h` stdout" assertion would be vacuous. If a future change introduces a protocol-variables help/docs section to the CLI, the implementer should remember that `PWD` must not be listed as an injected variable per Spec 6.1 / 8.3 / 13 — convert this item back into an executable test at that point. *(Spec 6.1, 11.2)*
+- **T-PWD-06**: CLI project root uses `process.cwd()`, not inherited `PWD`. SPEC 3.2 / 6.1 explicitly say "loopx does not consult `$PWD`" for project-root derivation — the CLI reads loopx's own `process.cwd()`. Spawn loopx with `PWD=/bogus-value-that-does-not-exist` in the inherited environment, while the actual kernel cwd (via the child-spawn's `cwd` option) is a real project directory (e.g., `/tmp/real-project/` containing `.loopx/ralph/index.ts`). TS fixture writes `$LOOPX_PROJECT_ROOT` via `observe-env` to a marker, also writes `process.cwd()` via `observe-cwd-ts`, and also writes the inherited `PWD` via `observe-env` with variable name `PWD` (reading `process.env.PWD` — not Bash `$PWD`, per the fixture note above). Assert: (a) `LOOPX_PROJECT_ROOT` equals the kernel cwd (something like `/tmp/real-project`), **not** `/bogus-value-that-does-not-exist`, (b) `process.cwd()` likewise reports the real cwd (directory identity matches; exact string spelling may be runtime-canonicalized), and (c) the `PWD`-via-`observe-env` marker records `{ "present": true, "value": "/bogus-value-that-does-not-exist" }` (inherited `PWD` passed through unchanged to the child per T-PWD-01, but loopx itself did not use it). This pins down the "loopx does not consult `$PWD`" rule concretely on the CLI project-root path — the existing T-PWD-* tests cover `PWD` passthrough but not that loopx ignores `PWD` for its own purposes. The TS fixture is used for the `PWD`-passthrough assertion so the comparison is against the env-map value rather than Bash's shell-level rewrite. *(Spec 3.2, 6.1, 13)*
+- **T-PWD-07**: `PWD` supplied via the **global** env file reaches spawned scripts. Per SPEC 6.1 / 8.3 / 13, `PWD` is **not** in the script-protocol-protected tier — env files (any tier) may supply `PWD` to spawned scripts, just like any other non-protocol variable. T-PWD-02 covers `RunOptions.env.PWD` passthrough and T-PWD-01/03 cover inherited-env `PWD` passthrough; this test closes the global env-file tier gap. Use `withGlobalEnv` to place a global env file containing `PWD=/value-from-global-env-file`. TS script observes `PWD` via `observe-env` (reading `process.env.PWD`, not Bash `$PWD` — per the fixture note above). Assert the marker records `{ "present": true, "value": "/value-from-global-env-file" }` — the global env-file value reaches the child unchanged because `PWD` is not at tier 1. The TS fixture is used so the assertion is against the env-map value, bypassing Bash's shell-level PWD rewrite. *(Spec 6.1, 8.1, 8.3, 13)*
+- **T-PWD-08**: `PWD` supplied via the **local (`-e`)** env file reaches spawned scripts. Same SPEC contract as T-PWD-07 but via the local env-file tier. Create a local env file containing `PWD=/value-from-local-env-file`. Run `loopx run -e <envfile> -n 1 ralph` via the CLI. TS script observes `PWD` via `observe-env`. Assert the marker records `{ "present": true, "value": "/value-from-local-env-file" }` — the local env-file value reaches the child unchanged. Together with T-PWD-02 (`RunOptions.env`), T-PWD-01/03 (inherited env), and T-PWD-07 (global env file), this completes four-tier coverage that `PWD` is supplied as a normal non-protocol variable from every supply tier — confirming SPEC 6.1 / 13's "intentionally not reserved" classification holds across all tiers (as opposed to the LOOPX_* protocol variables, which loopx injects at tier 1 regardless of lower-tier supply). *(Spec 6.1, 8.2, 8.3, 13)*
+
+#### Symlink / Project-Root Spelling
+
+Spec 3.2 / 6.1 declare loopx preserves discovery-time and caller-supplied spellings rather than canonicalizing via `realpath`. These tests close coverage gaps around symlinks on the project root and `.loopx/` layout.
+
+- **T-SYM-01**: Symlinked `.loopx` directory works end-to-end. Real workflows at `/tmp/real-loopx/ralph/index.sh` (outputs `stop:true`). Symlink `<project>/.loopx → /tmp/real-loopx`. `loopx run ralph` → exits 0, script executed. (Paired with T-WFDIR-11 which adds the env-var spelling assertion.) *(Spec 5.1, 6.1)*
+- **T-SYM-02**: CLI invocation from a symlinked project-root spelling — `LOOPX_PROJECT_ROOT` matches loopx's own `process.cwd()`. Real project at `/tmp/real-project/`. Symlink `/tmp/link-project → /tmp/real-project`. The SPEC guarantee (SPEC 3.2 / 6.1) is that CLI `LOOPX_PROJECT_ROOT` is **exactly the string returned by loopx's own `process.cwd()` at invocation** — SPEC additionally notes that POSIX `getcwd(3)` *typically* canonicalizes, so on most POSIX systems / runtimes this works out to the canonical `/tmp/real-project` form. But the binding contract is "matches `process.cwd()` of the loopx-runtime", **not** "matches `realpath(cwd)` on every POSIX/runtime combination" — runtime-version differences and exotic libc / kernel combinations could in principle preserve the symlinked spelling, in which case `LOOPX_PROJECT_ROOT` should preserve it too. The test must therefore **compute the expected value dynamically** rather than hardcode `/tmp/real-project`: in addition to the loopx run, the harness spawns the same runtime that loopx itself uses (Node or Bun, depending on the test matrix arm) with cwd set to `/tmp/link-project` and a tiny one-liner that prints `process.cwd()` to stdout, captures the printed value, and uses that as the expected `LOOPX_PROJECT_ROOT` value for the assertion. Concretely: (1) `cd /tmp/link-project` and run `<runtime> -e 'process.stdout.write(process.cwd())'` (or the runtime-equivalent), capture stdout into `expectedRoot`; (2) `cd /tmp/link-project && loopx run ralph` with fixture observing `LOOPX_PROJECT_ROOT` into a marker; (3) assert the marker value equals `expectedRoot` byte-for-byte. On the common POSIX configuration `expectedRoot` will be `/tmp/real-project` (the canonical form) and the assertion shape is identical to the historical hardcoded form, but on any runtime where `process.cwd()` preserves the symlinked spelling the test will still pass — because the SPEC contract is a `process.cwd()` equality, not a `realpath` equality. As a defensive supplemental assertion, also assert that `expectedRoot` resolves to the same directory identity (device/inode) as `/tmp/real-project` (via `stat`), which proves the symlink is intact and the test is exercising the symlinked-cwd path regardless of which spelling the runtime returned. Spec 6.1 "Directory identity vs. string spelling" — CLI `LOOPX_PROJECT_ROOT` is the `process.cwd()` spelling. *(Spec 3.2, 6.1)*
+- **T-SYM-02c**: CLI invocation from a symlinked project-root spelling — `LOOPX_WORKFLOW_DIR` and Bash `dirname "$0"` track the same `process.cwd()`-based root that `LOOPX_PROJECT_ROOT` does. T-SYM-02 pins down `LOOPX_PROJECT_ROOT` byte-for-byte equality with loopx's own `process.cwd()` at invocation; T-SYM-06 / T-SYM-06a pin down the corresponding `LOOPX_WORKFLOW_DIR` and Bash `$0` consistency on the **programmatic** surface (via `RunOptions.cwd`). The CLI counterpart for `LOOPX_WORKFLOW_DIR` and `$0` under a symlinked CLI cwd is not directly covered: T-SYM-02 only asserts `LOOPX_PROJECT_ROOT`, and T-SYM-06 / T-SYM-06a only exercise the programmatic surface. A buggy implementation that canonicalized via `realpath` along the cached workflow path on the CLI (or computed `dirname "$0"` from a `realpath`-canonicalized spawn path) could pass T-SYM-02 (project-root spelling preserved) and T-SYM-06 / T-SYM-06a (programmatic-surface spelling preserved) yet diverge on the CLI-side workflow-dir / `$0` axis. **Setup.** Real project at `/tmp/real-project/` containing `.loopx/ralph/index.sh` (the script records `LOOPX_PROJECT_ROOT`, `LOOPX_WORKFLOW_DIR`, and `$0` to a marker file via `printf '%s\n%s\n%s' "$LOOPX_PROJECT_ROOT" "$LOOPX_WORKFLOW_DIR" "$0" > "$MARKER_PATH"` then emits `stop: true`). Symlink `/tmp/link-project → /tmp/real-project`. **Compute the expected root dynamically** following T-SYM-02's pattern, since SPEC ties the value to `process.cwd()` (typically canonicalizing under POSIX `getcwd(3)` but not normatively): `cd /tmp/link-project` and run `<runtime> -e 'process.stdout.write(process.cwd())'` to capture `expectedRoot` for the loopx runtime arm under test. **Drive.** `cd /tmp/link-project && loopx run ralph` (CLI). **Assert.** (a) the marker's `LOOPX_PROJECT_ROOT` equals `expectedRoot` byte-for-byte (matches T-SYM-02's contract), (b) the marker's `LOOPX_WORKFLOW_DIR` is consistent with `expectedRoot/.loopx/ralph` — specifically equal to the lexical join `path.join(expectedRoot, ".loopx", "ralph")` byte-for-byte (which on the common POSIX configuration equals `/tmp/real-project/.loopx/ralph`, but is computed dynamically from `expectedRoot` to remain conformant under runtimes whose `process.cwd()` preserves the symlinked spelling), (c) `dirname "$0"` (computed in test code by stripping `/index.sh` from the recorded `$0`) equals the recorded `LOOPX_WORKFLOW_DIR` byte-for-byte — the SPEC 6.2 normative Bash equality. The test does **not** hardcode `/tmp/real-project` or `/tmp/link-project` as the expected `LOOPX_WORKFLOW_DIR` prefix; it derives both from `expectedRoot`, so the assertion is conformant under either canonicalizing or non-canonicalizing runtimes — the load-bearing contract is "consistent with `expectedRoot`", not "preserves the symlinked spelling". A defensive supplemental assertion verifies `expectedRoot` resolves to the same directory identity as `/tmp/real-project` (via `stat`), confirming the symlink is intact and the test exercised the symlinked-cwd path regardless of which spelling the runtime returned. Together with T-SYM-02 (CLI `LOOPX_PROJECT_ROOT`) and T-SYM-06 / T-SYM-06a (programmatic `LOOPX_WORKFLOW_DIR` / `$0` under symlinked `RunOptions.cwd`), this closes the CLI-side `LOOPX_WORKFLOW_DIR` / `$0` × symlinked-project-root coverage. *(Spec 3.2, 6.1, 6.2)*
+- **T-SYM-02d**: CLI invocation from a symlinked project-root spelling — effective-cwd directory identity matches `LOOPX_PROJECT_ROOT`. SPEC 6.1 "Directory identity vs. string spelling" specifies that loopx controls the child's *effective working directory* (same device/inode as the supplied path) but does not control the *string spelling* that runtime cwd APIs report. T-SYM-02 / T-SYM-02c pin down the CLI string-spelling preservation of `LOOPX_PROJECT_ROOT` and `LOOPX_WORKFLOW_DIR` under a symlinked CLI cwd; T-SYM-04d covers the corresponding **identity** half on the **programmatic** surface (under `RunOptions.cwd`). Neither directly asserts the identity half on the **CLI** surface — that the spawned child's effective cwd, even when its string spelling diverges from `LOOPX_PROJECT_ROOT`'s spelling, names the same directory as `LOOPX_PROJECT_ROOT` by device/inode under a symlinked CLI cwd. A buggy implementation that supplied the `process.cwd()` spelling to `child_process.spawn`'s `cwd` option but mis-resolved it (e.g., by accidentally re-rooting under a stale lexical path or by passing a different absolute path that happens to also have the same string prefix) could pass T-SYM-02 / T-SYM-02c (the env-var strings are correct) yet land the spawned child in a different directory. **Setup.** Real project at `/tmp/real-project/` containing `.loopx/ralph/index.sh`. Symlink `/tmp/link-project → /tmp/real-project`. The script records three values to a marker file: (1) `$LOOPX_PROJECT_ROOT` (the env-var string), (2) the device/inode pair of `.` (e.g., `stat -c '%d %i' .`), and (3) the device/inode pair of `$LOOPX_PROJECT_ROOT` (e.g., `stat -c '%d %i' "$LOOPX_PROJECT_ROOT"`). The harness, after the run, also captures `stat -c '%d %i' /tmp/link-project` for the cross-check. Following T-SYM-02's dynamic-`expectedRoot` pattern, the harness pre-spawns the loopx runtime under `cd /tmp/link-project` to capture `process.cwd()` into `expectedRoot` (typically `/tmp/real-project` under POSIX `getcwd(3)` canonicalization, but read dynamically rather than hardcoded so the test is conformant under runtimes whose `process.cwd()` preserves the symlinked spelling). **Drive.** `cd /tmp/link-project && loopx run ralph` (CLI). **Assert.** (a) the marker's `$LOOPX_PROJECT_ROOT` equals `expectedRoot` byte-for-byte (matches T-SYM-02's existing string-spelling guarantee — SPEC 3.2 / 6.1 "CLI `LOOPX_PROJECT_ROOT` is the `process.cwd()` spelling"), (b) the marker's device/inode pair from `stat .` equals the marker's device/inode pair from `stat "$LOOPX_PROJECT_ROOT"` (the script's effective cwd has the **same filesystem identity** as the directory named by the env-var string), and (c) both pairs equal the harness-captured device/inode pair of `/tmp/link-project` (which itself resolves to `/tmp/real-project`'s identity via the symlink). The test deliberately **does not assert byte-for-byte cwd string equality under symlinks** — SPEC 6.1 leaves the runtime-reported cwd string spelling implementation-defined (POSIX `getcwd(3)` typically canonicalizes via the kernel, but runtime-version differences and exotic libc / kernel combinations could in principle preserve the symlinked spelling). The **load-bearing identity assertion is (b)**, which is the SPEC 6.1 "effective working directory identity" clause pinned on the CLI surface. A defensive supplemental assertion verifies the harness-captured `/tmp/link-project` device/inode also matches `/tmp/real-project`'s device/inode (proves the symlink is intact and the test exercises the symlinked-cwd path). A buggy implementation that resolved the project-root via `realpath` before passing to `child_process.spawn`'s `cwd` option (and elsewhere preserved the `process.cwd()` spelling for `LOOPX_PROJECT_ROOT`) would still pass (a) / (b) / (c) — both string-spelling and identity match the same underlying directory — so the test does not catch that specific class of canonicalization. The test catches implementations that diverge cwd from `LOOPX_PROJECT_ROOT`'s identity (e.g., by passing a different absolute path or by accidentally landing in a stale prior-iteration cwd). T-SYM-02 / T-SYM-02c pin the string spelling on the CLI surface; T-SYM-04d pins the identity invariant on the programmatic surface; this test pins the identity invariant on the CLI surface, completing the {string-spelling, identity} × {CLI, programmatic} matrix for symlinked project roots. *(Spec 3.2, 6.1)*
+- **T-SYM-03**: Programmatic `cwd` preserves symlink spelling (no `realpath`). Real project at `/tmp/real-project/`. Symlink `/tmp/link-project → /tmp/real-project`. Call `runPromise("ralph", { cwd: "/tmp/link-project", maxIterations: 1 })`. Fixture observes `LOOPX_PROJECT_ROOT`. Assert marker is `/tmp/link-project` — the symlink spelling supplied via `RunOptions.cwd` is preserved verbatim, not canonicalized. *(Spec 3.2, 6.1, 9.5)*
+- **T-SYM-04**: Programmatic `cwd` under a symlinked ancestor is preserved verbatim. Real project at `/tmp/real-outer/proj/`. Symlink `/tmp/link-outer → /tmp/real-outer`. Call `runPromise("ralph", { cwd: "/tmp/link-outer/proj", maxIterations: 1 })`. Assert `LOOPX_PROJECT_ROOT` is `/tmp/link-outer/proj` — lexical resolution via `path.resolve` only, no `realpath`. *(Spec 3.2, 6.1, 9.5)*
+- **T-SYM-04a**: Absolute `RunOptions.cwd` with a trailing slash has its supplied spelling preserved verbatim. SPEC 9.5 says: "If `cwd` is absolute, it is used unchanged; no `realpath`, and unlike a relative `cwd`, no `path.resolve()` normalization." Create a real project at `/tmp/real-project/` containing `.loopx/ralph/index.sh`. Call `runPromise("ralph", { cwd: "/tmp/real-project/", maxIterations: 1 })` — note the trailing slash. Fixture observes `LOOPX_PROJECT_ROOT` into a marker. Assert the marker value is **byte-for-byte equal** to `"/tmp/real-project/"` — the trailing slash is preserved. An implementation that called `path.resolve()` on the absolute value would strip the trailing slash (since `path.resolve("/tmp/real-project/")` returns `"/tmp/real-project"`); SPEC 9.5 explicitly forbids that normalization. This test pins down the "used unchanged" clause as a byte-for-byte equality against the caller-supplied spelling, distinct from the symlink-preservation coverage in T-SYM-03 / T-SYM-04 (which cover symlinked absolute paths but where trailing-slash behavior is incidental). T-SYM-04b covers the lexical `..` component variant. *(Spec 9.5, 6.1)*
+- **T-SYM-04b**: Absolute `RunOptions.cwd` containing lexical `..` components has its supplied spelling preserved verbatim. Same SPEC 9.5 "used unchanged" clause as T-SYM-04a. Create a real project at `/tmp/real-project/` and a sibling `/tmp/adjacent/`, so that the lexical path `/tmp/adjacent/../real-project` resolves to the same directory but with a non-canonical spelling. Call `runPromise("ralph", { cwd: "/tmp/adjacent/../real-project", maxIterations: 1 })`. Fixture observes `LOOPX_PROJECT_ROOT` into a marker. Assert the marker value is byte-for-byte equal to `"/tmp/adjacent/../real-project"` — the lexical `..` component is preserved. An implementation that called `path.resolve()` or `path.normalize()` would collapse the `..` component to `"/tmp/real-project"`; SPEC 9.5 explicitly contrasts the absolute-cwd "no `path.resolve()` normalization" rule with the relative-cwd normalization path. Together T-SYM-04a / T-SYM-04b pin down two distinct normalization-suppression modes (trailing slash and `..` components) for the absolute-cwd-unchanged contract. *(Spec 9.5, 6.1)*
+- **T-SYM-04c**: Workflow-dir consistency under absolute `RunOptions.cwd` trailing-slash and lexical `..` spellings — `LOOPX_WORKFLOW_DIR` and Bash `dirname "$0"` track the caller-supplied spelling, and Bash `dirname "$0"` equals `LOOPX_WORKFLOW_DIR` byte-for-byte (SPEC 6.2 normative equality). T-SYM-04a / T-SYM-04b pin down `LOOPX_PROJECT_ROOT` preservation under those two non-canonical absolute spellings; this test extends the same coverage to `LOOPX_WORKFLOW_DIR` and the Bash-`$0` equality contract on the same spellings, ensuring the cached discovery-time path that loopx injects as `LOOPX_WORKFLOW_DIR` and uses to spawn the script is consistent under non-canonical project-root spellings — without over-pinning any implementation-defined lexical normalization beyond SPEC 6.2's byte-for-byte Bash equality. **Parameterize over two variants:** variant (a) **trailing slash** — `cwd: "/tmp/real-project/"`; variant (b) **lexical `..`** — `cwd: "/tmp/adjacent/../real-project"` (with `/tmp/adjacent/` pre-created). For each variant, set up `.loopx/ralph/index.sh` that records `LOOPX_PROJECT_ROOT`, `LOOPX_WORKFLOW_DIR`, and `$0` to a marker file (e.g., `printf '%s\n%s\n%s' "$LOOPX_PROJECT_ROOT" "$LOOPX_WORKFLOW_DIR" "$0" > "$MARKER_PATH"`) and emits `stop: true`. Call `runPromise("ralph", { cwd: <variant>, maxIterations: 1 })`. Assert per variant: (a) the promise resolves; (b) `dirname "$0"` (computed in test code from the recorded `$0`) equals the recorded `LOOPX_WORKFLOW_DIR` **byte-for-byte** — the SPEC 6.2 normative Bash equality holds under both non-canonical absolute-cwd spellings; (c) the recorded `LOOPX_WORKFLOW_DIR` is consistent with the actual spawn path — the script ran, the marker exists, and the marker's `$0` is the absolute path loopx used to spawn the script (verifiable by checking that the entry-script file at `<recorded $0>` is the same file as `/tmp/real-project/.loopx/ralph/index.sh` via `stat`); (d) the assertion explicitly does **not** over-pin any implementation-defined lexical normalization beyond the byte-for-byte Bash equality — for variant (a), the test does **not** require `LOOPX_WORKFLOW_DIR` to literally include `//` from the trailing slash propagating into `<cwd>/.loopx/ralph` (some implementations may collapse double-slashes lexically, others may not — SPEC 6.1 is silent), and for variant (b) the test does **not** require `LOOPX_WORKFLOW_DIR` to literally include `..` (the cached discovery-time path may have been computed via `path.join` or via direct concatenation — SPEC 6.1 is silent); the **only** structural assertion is the Bash equality (b) and the same-file identity (c). This test extends T-SYM-04a / T-SYM-04b (which cover `LOOPX_PROJECT_ROOT` byte-for-byte preservation under those exact non-canonical spellings) into the `LOOPX_WORKFLOW_DIR` / Bash-`$0` axis, completing the workflow-dir consistency coverage without overconstraining. *(Spec 6.1, 6.2, 9.5)*
+- **T-SYM-04d**: Effective-cwd directory identity under symlinked `RunOptions.cwd` — `LOOPX_PROJECT_ROOT` preserves the symlinked spelling while the spawned script's effective cwd has the same device/inode as that path. SPEC 6.1 "Directory identity vs. string spelling" specifies that loopx controls the child's *effective working directory* by spawning with `LOOPX_PROJECT_ROOT` as cwd (same device/inode as the supplied path) but does not control the *string spelling* that runtime cwd APIs report. T-SYM-03 / T-SYM-04 cover the string-spelling preservation of `LOOPX_PROJECT_ROOT` under symlinked `RunOptions.cwd` (lexical resolution via `path.resolve` only, no `realpath`); T-SYM-06 / T-SYM-06a / T-SYM-04c cover the same string-spelling preservation for `LOOPX_WORKFLOW_DIR` and Bash `$0`. None of those directly assert the **identity** half of SPEC 6.1's clause — that the script's effective cwd, even when its string spelling diverges from `LOOPX_PROJECT_ROOT`'s spelling, names the same directory as `LOOPX_PROJECT_ROOT` by device/inode. A buggy implementation that supplied the symlinked spelling to `child_process.spawn`'s `cwd` option but mis-resolved it (e.g., by accidentally re-rooting under a stale lexical path or by passing a different absolute path that happens to also have the same string prefix) could pass T-SYM-03 / T-SYM-04 (the env-var string is correct) yet land the spawned child in a different directory. **Setup.** Real project at `/tmp/real-project/` containing `.loopx/ralph/index.sh`. Symlink `/tmp/link-project → /tmp/real-project`. The script records three values to a marker file: (1) `$LOOPX_PROJECT_ROOT` (the env-var string), (2) `pwd -P` (the kernel-reported effective cwd, typically canonicalized via `getcwd(3)`), and (3) the device/inode pair of `.` (e.g., `stat -c '%d %i' .`). The harness, after the run, also captures `stat -c '%d %i' /tmp/link-project` (the device/inode of the supplied symlinked spelling, which resolves to `/tmp/real-project`'s identity) for the cross-check. **Drive.** Call `runPromise("ralph", { cwd: "/tmp/link-project", maxIterations: 1 })`. **Assert.** (a) the promise resolves; (b) the marker's `$LOOPX_PROJECT_ROOT` equals `"/tmp/link-project"` byte-for-byte (matching T-SYM-03's existing string-spelling guarantee — preserved verbatim, no `realpath` applied); (c) the marker's device/inode pair from `stat .` equals the harness-captured device/inode pair of `/tmp/link-project` (the script's effective cwd has the **same filesystem identity** as the supplied `RunOptions.cwd`, which is also the same identity as `/tmp/real-project` because the symlink resolves there); and (d) the marker's `pwd -P` value typically reports `/tmp/real-project` (the kernel-canonicalized form via `getcwd(3)`) rather than `/tmp/link-project` — the test does **not** require this byte-for-byte (SPEC 6.1 leaves `pwd -P` runtime-defined and notes runtime canonicalization is "typical" but not normatively pinned), but the harness records it for diagnostic purposes; the **load-bearing identity assertion is (c)**. A defensive supplemental assertion verifies the harness-captured `/tmp/link-project` device/inode also matches `/tmp/real-project`'s device/inode (proves the symlink is intact and the test exercises the symlinked path). A buggy implementation that resolved `RunOptions.cwd` via `realpath` before passing to `child_process.spawn`'s `cwd` option (and elsewhere preserved the symlinked spelling for `LOOPX_PROJECT_ROOT`) would still pass (b) and (c) — both string-spelling and identity match the same underlying directory — so the test does not catch that specific class of canonicalization. The test catches implementations that diverge cwd from `LOOPX_PROJECT_ROOT`'s identity (e.g., by passing a different absolute path or by accidentally landing in a stale prior-iteration cwd). T-SYM-03 / T-SYM-04 pin the string spelling; this test pins the identity invariant on the same programmatic surface. *(Spec 3.2, 6.1, 9.5)*
+- **T-SYM-05**: `LOOPX_WORKFLOW_DIR` uses cached discovery-time spelling, not recomposition. `<project>/.loopx` is a real directory; `<project>/.loopx/ralph` is a symlink to `/tmp/real-ralph/` (where `/tmp/real-ralph/index.sh` lives). Run `loopx run ralph`. Observe `LOOPX_PROJECT_ROOT` and `LOOPX_WORKFLOW_DIR`. Assert: `LOOPX_WORKFLOW_DIR == "<project>/.loopx/ralph"` (the discovered, symlinked spelling) — **not** `/tmp/real-ralph`, and **not** the lexically-recomposed `path.join(LOOPX_PROJECT_ROOT, ".loopx", "ralph")` if lexical recomposition would diverge from the cached discovery path. For the symlink-on-`.loopx/<workflow>` case those happen to coincide, so this test uses a second project where `<project>/.loopx` itself is a symlink to `/tmp/real-loopx`, and `<project>/.loopx/ralph` is a plain directory underneath — then `LOOPX_WORKFLOW_DIR` must be `<project>/.loopx/ralph` (the cached path at discovery time), not `/tmp/real-loopx/ralph` (the realpath-canonicalized form). *(Spec 6.1)*
+- **T-SYM-06**: `LOOPX_WORKFLOW_DIR` preserves the symlink spelling coming from `RunOptions.cwd` in its project-root prefix. Per SPEC 6.1 "Symlink behavior": "A symlinked ... project-root ancestor (via `RunOptions.cwd`) all preserve their discovered spelling in `LOOPX_WORKFLOW_DIR`." Set up a real project at `/tmp/real-project/` containing `.loopx/ralph/index.sh` (observes `LOOPX_WORKFLOW_DIR`). Symlink `/tmp/link-project → /tmp/real-project`. Call `runPromise("ralph", { cwd: "/tmp/link-project", maxIterations: 1 })`. Observe `LOOPX_WORKFLOW_DIR`. Assert: the marker equals `"/tmp/link-project/.loopx/ralph"` (the symlink-preserved spelling anchored at the caller-supplied `cwd`) — **not** `"/tmp/real-project/.loopx/ralph"` (the realpath-canonicalized form), and **not** any other lexical transform that would discard the `/tmp/link-project` prefix. A buggy implementation that called `realpath` on the cached discovery-time workflow path — even though no component under `.loopx/` is symlinked — would fail this assertion because `realpath` would canonicalize the `/tmp/link-project` prefix to `/tmp/real-project`. T-SYM-03 / T-SYM-04 cover the `LOOPX_PROJECT_ROOT` surface on this path; T-SYM-05 covers the `LOOPX_WORKFLOW_DIR` symlink-on-`.loopx/` surface under an unmodified CLI cwd; this test closes the gap where the symlink lives in the project-root ancestor supplied via `RunOptions.cwd` rather than in the discovery path below the project root. *(Spec 3.2, 6.1, 9.5)*
+- **T-SYM-06a**: Bash `$0` preserves the symlink spelling coming from `RunOptions.cwd` in its project-root prefix. Per SPEC 6.2: "loopx invokes each script using its absolute discovery-time path ... Bash does not canonicalize `$0`, so `$(dirname "$0")` equals `LOOPX_WORKFLOW_DIR` byte-for-byte regardless of whether symlinks appear anywhere in the entry path (workflow directory entry, entry script file, or intermediate component). This Bash equality is normative." T-SYM-06 covers `LOOPX_WORKFLOW_DIR` under a symlinked project root via `RunOptions.cwd`; this test pins down the Bash `$0` counterpart, closing the parity gap against SPEC 6.2's normative byte-for-byte equality clause. Set up a real project at `/tmp/real-project/` containing `.loopx/ralph/index.sh`; symlink `/tmp/link-project → /tmp/real-project`. The script records **both** `$0` and `LOOPX_WORKFLOW_DIR` into an external marker file (e.g., `printf '%s\n%s' "$0" "$LOOPX_WORKFLOW_DIR" > "$MARKER_PATH"`), then emits `stop: true`. Call `runPromise("ralph", { cwd: "/tmp/link-project", maxIterations: 1 })`. Assert: (a) the promise resolves, (b) the marker's `$0` equals `"/tmp/link-project/.loopx/ralph/index.sh"` (the symlink-preserved spelling anchored at the caller-supplied `cwd`) — **not** `"/tmp/real-project/.loopx/ralph/index.sh"` (realpath-canonicalized form), (c) the marker's `LOOPX_WORKFLOW_DIR` equals `"/tmp/link-project/.loopx/ralph"` (matching T-SYM-06's assertion), and (d) `dirname "$0"` equals `$LOOPX_WORKFLOW_DIR` byte-for-byte (the SPEC 6.2 normative Bash equality — asserted by stripping `/index.sh` from the `$0` marker and comparing with the workflow-dir marker). A buggy implementation that canonicalized the spawn-path via `realpath` before invoking Bash would produce `/tmp/real-project/...` in `$0` and break the SPEC 6.2 Bash equality guarantee. T-SYM-02 / T-SYM-02a / T-SYM-02b cover Bash `$0` under symlinked `.loopx` / workflow-directory / entry-script symlinks but under an unmodified CLI cwd; this test closes the gap where the symlink lives in the project-root ancestor supplied via `RunOptions.cwd`. *(Spec 3.2, 6.1, 6.2, 9.5)*
+- **T-SYM-07**: `[Node]` `import.meta.url` vs. `LOOPX_WORKFLOW_DIR` — symlink-free entry path equality. Per SPEC 6.3 "Because loopx invokes each script using its absolute discovery-time path (section 6.1), `dirname(fileURLToPath(import.meta.url))` equals `LOOPX_WORKFLOW_DIR` only when the absolute entry path is symlink-free in every component." Set up `.loopx/ralph/index.ts` at a **symlink-free** real path (no component of the project root, `.loopx/`, `ralph/`, or `index.ts` is a symlink). The script imports `output` from loopx, computes `dirname(fileURLToPath(import.meta.url))`, and writes `{ workflowDir: process.env.LOOPX_WORKFLOW_DIR, importMetaDir: <computed> }` to a marker file before calling `output({ stop: true })`. Run via `runPromise("ralph", { maxIterations: 1 })` under Node.js. Assert: (a) exit code 0, (b) the marker's `workflowDir` and `importMetaDir` are **byte-for-byte equal** — SPEC 6.3 guarantees equality in the symlink-free case. `[Node]` *(Spec 6.1, 6.3)*
+- **T-SYM-07a**: `[Node]` `import.meta.url` vs. `LOOPX_WORKFLOW_DIR` — symlinked entry path divergence. Companion to T-SYM-07 covering the second half of the SPEC 6.3 caveat ("only when ... symlink-free"). Set up a real script at `/tmp/real-ralph/index.ts` and symlink `<project>/.loopx/ralph/index.ts → /tmp/real-ralph/index.ts` (alternatively, symlink `<project>/.loopx/ralph → /tmp/real-ralph` — either path-component symlink variant is admissible). The script writes `{ workflowDir: process.env.LOOPX_WORKFLOW_DIR, importMetaDir: dirname(fileURLToPath(import.meta.url)) }` to a marker file. Run via `runPromise("ralph", { maxIterations: 1 })` under Node.js — Node applies `realpath` to the main module's file path by default, so the `import.meta.url`-derived path will canonicalize while `LOOPX_WORKFLOW_DIR` will preserve the discovery-time spelling. Assert: (a) exit code 0, (b) `marker.workflowDir` is the **discovery-time spelling** (the symlinked workflow path under `<project>/.loopx/ralph` — what T-WFDIR-11 / T-SYM-05 guarantee), (c) `marker.importMetaDir !== marker.workflowDir` — they diverge because Node canonicalized the entry path, and (d) `marker.workflowDir` (not `marker.importMetaDir`) is the authoritative surface per SPEC 6.3 "`LOOPX_WORKFLOW_DIR` is authoritative for JS/TS code that needs the discovery-time workflow path." Tests the SPEC 6.3 clause that loopx does not pass runtime-specific symlink-preservation flags to Node. `[Node]` *(Spec 6.1, 6.3)*
+- **T-SYM-07b**: `[Bun]` `import.meta.url` vs. `LOOPX_WORKFLOW_DIR` — symlink-free entry path equality under Bun. Bun counterpart to T-SYM-07. SPEC 6.3 covers JS/TS scripts under both Node/tsx and Bun ("When running under Bun, loopx uses Bun's native TypeScript/JSX support instead of `tsx`"); the equality clause "`dirname(fileURLToPath(import.meta.url))` equals `LOOPX_WORKFLOW_DIR` only when the absolute entry path is symlink-free in every component" is runtime-agnostic for the **symlink-free** case — both runtimes spawn the script using the same absolute discovery-time path that loopx records as `LOOPX_WORKFLOW_DIR/<entry>`, and `import.meta.url` reflects the URL that was actually loaded. Only the symlinked-divergence half of the SPEC 6.3 caveat is runtime-caveated (Node applies `realpath` by default; "Bun's behavior is not specified to match"); a Bun symlink-divergence assertion is intentionally **not** added here because SPEC 6.3 does not require Bun to match Node's symlink realpath behavior, and pinning a specific divergence direction would over-constrain the implementation. **Setup matches T-SYM-07 verbatim:** `.loopx/ralph/index.ts` at a **symlink-free** real path (no component of the project root, `.loopx/`, `ralph/`, or `index.ts` is a symlink); the script imports `output` from loopx, computes `dirname(fileURLToPath(import.meta.url))`, and writes `{ workflowDir: process.env.LOOPX_WORKFLOW_DIR, importMetaDir: <computed> }` to a marker file before calling `output({ stop: true })`. **Drive under Bun** (e.g., `bun /abs/path/to/dist/cli.js run -n 1 ralph` or the project's standard Bun-CLI entry, mirroring T-INST-GLOBAL-01a / T-MOD-03e-bun's Bun-driver pattern), against the symlink-free project as cwd. Assert: (a) exit code 0, (b) the marker's `workflowDir` and `importMetaDir` are **byte-for-byte equal** — SPEC 6.3 guarantees equality in the symlink-free case under both Node and Bun. **Conditional on Bun being available in the test environment** (gated like other `[Bun]` tests). Together with T-SYM-07 (Node), this closes the symlink-free-equality gap on both supported JS/TS runtimes for SPEC 6.3. `[Bun]` *(Spec 6.1, 6.3)*
+
 ### 4.8 Module Resolution & Script Helpers
 
 **Spec refs:** 3.3, 3.4, 6.4, 6.5
@@ -1043,8 +1999,17 @@ All env file parsing tests below use `writeEnvFileRaw` to write exact file conte
 - **T-MOD-02**: Same import works under Bun. `[Bun]` *(Spec 3.3)*
 - **T-MOD-03**: A JS script with `import { output } from "loopx"` also works. *(Spec 3.3)*
 - **T-MOD-03a**: A workflow that has its own `node_modules/loopx` (a different version) resolves `import from "loopx"` to the **local** package, not the running CLI's package. Standard module resolution applies — the closest `node_modules` wins. The workflow-local `node_modules/loopx` package must export a sentinel value (e.g., a unique marker string from a custom `output()` or an additional export) that differs from the CLI-provided package. The test script imports from `"loopx"` and writes the sentinel to a marker file. Assert: (a) the marker file contains the workflow-local sentinel, proving the local package was actually loaded (not just that the CLI didn't warn), and (b) **no warning is emitted on stderr** — per Spec 3.3, no warning is emitted for workflow-local `node_modules/loopx` resolution in v1. *(Spec 3.3, 2.1)*
-- **T-MOD-03b**: Combined precedence: project-root delegation is active (project-root `package.json` declares `loopx`, `node_modules/.bin/loopx` exists) **and** the target workflow has its own `node_modules/loopx` with a different sentinel export. The test script imports from `"loopx"` and writes the resolved sentinel to a marker file. Assert: the marker file contains the **workflow-local** sentinel, not the project-root delegated package's sentinel. This tests the full Spec 3.3 precedence chain — delegation determines which CLI binary runs, but `import "loopx"` within a script resolves to the closest `node_modules/loopx` (the workflow-local one), not the delegated project-root one. T-MOD-03a tests workflow-local vs. CLI without delegation; T-DEL-06 tests delegation without workflow-local; this test combines both and asserts the workflow-local package wins. *(Spec 3.3, 3.2)*
-- **T-MOD-03c**: Workflow-level `package.json` `type` field is respected for intra-workflow `.js` module resolution. Create `.loopx/ralph/package.json` with `{ "type": "module" }`, `.loopx/ralph/lib/helper.js` containing `export const value = "esm-resolved";` (ESM named export), and `.loopx/ralph/index.ts` that does `import { value } from "./lib/helper.js"; import { output } from "loopx"; output({ result: value });`. Run `loopx run -n 1 ralph` under Node.js. Assert: (a) exit code 0, and (b) output result is `"esm-resolved"`. The `.ts` entry point is executed via tsx, but the imported `.js` helper in `lib/` is resolved through Node.js's standard module system, where the nearest `package.json` `type` field determines whether `.js` files are treated as ESM. This verifies that loopx's execution model (workflow directory as cwd, per Spec 6.1) correctly exposes the workflow's `package.json` `type` field to Node.js module resolution for intra-workflow imports. `[Node]` *(Spec 2.1, 3.3)*
+- **T-MOD-03b**: Combined precedence: project-root delegation is active (project-root `package.json` declares `loopx`, `node_modules/.bin/loopx` exists) **and** the target workflow has its own `node_modules/loopx` with a different sentinel export. The test script imports from `"loopx"` and writes the resolved sentinel to a marker file. Assert: (a) the marker file contains the **workflow-local** sentinel, not the project-root delegated package's sentinel, and (b) **no warning is emitted on stderr** about the workflow-local resolution (no helper-version-divergence warning, no delegation-path warning) — per SPEC 3.3, no warning is emitted for workflow-local `node_modules/loopx` resolution in v1, and that no-warning rule must hold under delegation as well. This tests the full SPEC 3.3 precedence chain — delegation determines which CLI binary runs, but `import "loopx"` within a script resolves to the closest `node_modules/loopx` (the workflow-local one), not the delegated project-root one — and the SPEC 3.3 no-warning guarantee is independent of whether delegation fires. T-MOD-03a tests workflow-local vs. CLI without delegation and asserts the no-warning guarantee at that surface; T-DEL-06 tests delegation without workflow-local; this test combines both and asserts both the workflow-local-wins outcome and the no-warning guarantee in the combined-precedence configuration. A buggy implementation that emitted a divergence warning only when delegation was active (e.g., as a "post-delegation helper-version mismatch" check) would fail assertion (b) here while passing T-MOD-03a's no-warning assertion. *(Spec 3.3, 3.2)*
+- **T-MOD-03c**: Workflow-level `package.json` `type` field is respected for intra-workflow `.js` module resolution. Create `.loopx/ralph/package.json` with `{ "type": "module" }`, `.loopx/ralph/lib/helper.js` containing `export const value = "esm-resolved";` (ESM named export), and `.loopx/ralph/index.ts` that does `import { value } from "./lib/helper.js"; import { output } from "loopx"; output({ result: value });`. Observe via `runPromise("ralph", { maxIterations: 1, cwd: project.dir })` under Node.js — SPEC 7.1 specifies that the CLI never prints `result` to stdout, so the programmatic API is the correct observation surface for yielded `Output.result`. Assert: (a) `runPromise` resolves (no rejection), and (b) the returned array's single `Output` has `result === "esm-resolved"`. The `.ts` entry point is executed via tsx, but the imported `.js` helper in `lib/` is resolved through Node.js's standard module system, where the nearest `package.json` `type` field determines whether `.js` files are treated as ESM. This verifies **file-relative module resolution**: Node ESM walks up from the importing module's path (not from cwd — cwd remains project-root per Spec 6.1) to find the nearest `package.json`, and the workflow-local `package.json` is the nearest one relative to `.loopx/ralph/lib/helper.js`, so its `"type": "module"` field governs how the imported `.js` helper is treated. `[Node]` *(Spec 2.1, 3.3, 7.1)*
+- **T-MOD-03d**: Symlink caveat for JS/TS entry paths — under a symlinked **entry script**, a workflow-local `node_modules/loopx` on the **logical** path may not win, and loopx emits no warning. `[Node]` SPEC 3.3's "Symlink caveat for JS/TS entry paths" clarifies that Node's default main-module handling applies `realpath` to the main module's file path, so when the absolute discovery-time entry path traverses any symlink, the resolver walks up from the canonical target rather than the symlink-preserving spelling. Set up: a real workflow directory at `/tmp/project/.loopx/ralph/` (not itself a symlink) containing (a) a symlinked entry script `/tmp/project/.loopx/ralph/index.ts -> /tmp/real-entry/index.ts` where the real entry script at `/tmp/real-entry/index.ts` contains `import { output } from "loopx"; output({ result: "from-cli-fallback", stop: true });`, and (b) a workflow-local `node_modules/loopx/` at `/tmp/project/.loopx/ralph/node_modules/loopx/` (on the *logical* path). **The workflow-local stub must be observable independently of argument evaluation order** — a previous design relied on a sentinel set inside `output()` that the script then read on the next iteration's argument, but that design false-passes because the argument is evaluated before `output()` runs. Two independent observation channels are wired so a regression that loaded the local stub fails on at least one channel, regardless of evaluation timing: (i) the local stub's `index.js` (the package `main`) has a **top-level side effect** that runs at module-import time — it writes a marker file at `$LOOPX_PROJECT_ROOT/marker-local-stub-imported.txt` containing the literal string `"from-workflow-local"` immediately on import, before any `output()` call can happen, and (ii) the local stub's exported `output()` **ignores its argument** and emits `{ result: "from-workflow-local", stop: true }` to stdout (so if the local stub is loaded, the yielded `Output.result` is `"from-workflow-local"`, not the script's argument `"from-cli-fallback"`). The stub's `package.json` declares `{ "name": "loopx", "type": "module", "main": "./index.js" }`. **Do not** place a `node_modules/loopx` under `/tmp/real-entry/` — if one existed there, realpath-based resolution would find it. Observe via `runPromise("ralph", { maxIterations: 1, cwd: "/tmp/project" })` under Node.js — SPEC 7.1 specifies that the CLI never prints `result` to stdout, so the programmatic API is the correct observation surface for yielded `Output.result`. Assert: (a) `runPromise` resolves (no rejection), (b) the returned array's single `Output` has `result === "from-cli-fallback"` (the CLI-provided fallback's `output()` serialized the script's argument unmodified), **not** `"from-workflow-local"` — Node's main-module `realpath` resolved the entry to `/tmp/real-entry/index.ts`, and the resolver walked up from `/tmp/real-entry/` rather than the symlink-preserving `/tmp/project/.loopx/ralph/`, so the workflow-local `node_modules/loopx` on the logical path is not on the resolved module-resolution path; (c) **the marker file `/tmp/project/marker-local-stub-imported.txt` does NOT exist** — the local stub was never imported, proving the realpath-canonicalized resolution did not visit the logical path's `node_modules/loopx/`; and (d) stderr contains **no warning** about the workflow-local `node_modules/loopx` being bypassed — per SPEC 3.3 "No warning is emitted for this scenario in v1." Assertions (b) and (c) are independent witnesses to "local stub not loaded": (b) catches a stub whose top-level import succeeded but whose `output()` got called with the script's argument; (c) catches a stub whose import-time side effect ran but whose `output()` was never called (e.g., because the script crashed before reaching it). Either assertion firing alone proves a regression. (Note: the earlier variant that symlinked `.loopx/ralph` itself to `/tmp/real-workflow/` and placed the logical `node_modules/loopx` inside the symlinked workflow dir is **not** a valid reproduction — a `node_modules/` inside a symlinked directory is physically written under the symlink target, so Node's realpath resolver will find it, producing the opposite outcome. The symlinked-entry-script fixture above is the correct shape for this caveat.) T-MOD-03a covers the normal (non-symlinked) precedence where workflow-local wins; this test is the symlink-caveat counterpart and locks down the documented exception. `[Node]` *(Spec 3.3, 7.1)*
+- **T-MOD-03e**: Project-root `node_modules/loopx` wins over CLI fallback for **scripts** — **independently of delegation**. SPEC 3.3 "Resolution precedence" states: "Standard file-relative resolution of `"loopx"` from the importing module's path always wins; the CLI-provided fallback applies only when no `node_modules/loopx` is found by standard resolution. This precedence is independent of cwd" — and, importantly, independent of delegation. T-MOD-03a covers workflow-local `node_modules/loopx`, T-MOD-03b covers the combined workflow-local + delegation case, and T-DEL-06 covers the delegated-version's package; but none of those exercise the **project-root** `node_modules/loopx` as a resolution target for the spawned script when delegation does **not** happen. Set up: (a) a project at `/tmp/project/` with **no** project-root `package.json` declaring `loopx` (or a `package.json` that does not declare `loopx`), so project-root delegation is skipped per SPEC 3.2; (b) install a project-root `node_modules/loopx` at `/tmp/project/node_modules/loopx/` — this is a **marker-only stub package**, not a runnable loopx implementation; its `index.js` (the `package.json` `main`) is an ESM module that **exports a deterministic `output(value)` function** that (i) writes a fixed sentinel string `"from-project-root-stub"` to a marker file at `$LOOPX_PROJECT_ROOT/marker-resolved-stub.txt`, (ii) writes **valid loopx structured JSON** to `process.stdout` — specifically `JSON.stringify({ stop: true, result: "from-project-root-stub" }) + "\n"` — so the loopx parent parses a well-formed Output, and (iii) calls `process.exit(0)`. The stub's `package.json` declares `{ "name": "loopx", "type": "module", "main": "./index.js" }`. Because the stub produces a valid `stop: true` Output, the CLI's exit-code outcome is pinned down deterministically — not "whatever the stub dictates"; (c) `.loopx/ralph/index.ts` containing `import { output } from "loopx"; output({ result: "from-stub" });` and **no** workflow-local `node_modules/loopx`. **Drive the run via the CLI, not via `runPromise()`** — invoke `loopx run -n 1 ralph` against `/tmp/project/` as cwd (e.g., via `runCLI`). The CLI surface is required here because a programmatic driver process invoked from the test harness would itself import `"loopx"` to call `runPromise()`, and Node's standard module resolution from the driver's importing path may walk up to `/tmp/project/node_modules/loopx/` and resolve the **stub** in place of the implementation under test, breaking the driver before the spawned script even runs (the driver is **not** the test subject — the spawned script is). The CLI invocation does not have this hazard because the CLI binary's own `"loopx"` imports resolve from the global / dist install path, not from `/tmp/project/`. The spawned `.loopx/ralph/index.ts` script, however, does have its importing path under `/tmp/project/.loopx/ralph/`, so its bare `import "loopx"` walks up to `/tmp/project/node_modules/loopx/` and resolves the stub. Assert: (a) **the CLI exits 0** — the stub's structured `{ stop: true, result: "from-project-root-stub" }` output is parsed by loopx and halts the loop cleanly on the first iteration; the previous "or whatever the stub dictates" escape hatch is removed, so a regression that caused the stub not to be loaded (CLI fallback resolved instead) would surface as a non-zero exit or missing marker, not as an acceptable outcome. (b) No delegation occurred (verify via an `observe-env`-style marker for `LOOPX_BIN` recorded by a Bash pre-fixture before the TS script runs, or by asserting the absence of a delegation-side marker that a second `node_modules/.bin/loopx` would have written had it been invoked). (c) The marker file `marker-resolved-stub.txt` exists with content exactly `"from-project-root-stub"` — proving the spawned script's `import { output } from "loopx"` resolved to the project-root stub rather than the CLI's own loopx package. **Driver-side alternative:** a programmatic test that wants to assert this contract via `runPromise()` instead of the CLI **must** import the implementation under test by absolute path (e.g., `import { runPromise } from "/abs/path/to/dist/index.js"`) so the driver's own `"loopx"` resolution does not walk up to `/tmp/project/node_modules/loopx/` and resolve the stub. The spawned workflow script `.loopx/ralph/index.ts` continues to use bare `import "loopx"`, which still resolves to the project-root stub from the script's importing path. This proves that standard Node/tsx module resolution walks up from the importing **script's** path and finds the project-root `node_modules/loopx` — **even though delegation did not happen** — so a buggy implementation that tied helper resolution to whether delegation fired (e.g., by routing `"loopx"` resolution through the delegated-CLI path) would fail this test. Without this gap-closer, the existing T-MOD-03a/03b/03d coverage could leave a resolution-delegation coupling undetected. `[Node]` *(Spec 3.3, 3.2, 7.1)*
+- **T-MOD-03e-bun**: `[Bun]` Project-root `node_modules/loopx` wins over CLI fallback for **scripts** — **independently of delegation** — under Bun. Bun counterpart to T-MOD-03e. SPEC 3.3 "Resolution precedence" applies standard file-relative resolution to **both** runtimes, not Node alone — workflow-local-vs-CLI-fallback behavior is covered for Node (T-MOD-03a) and the bare-import case is covered for Bun (T-MOD-02), but the project-root / non-delegation case is currently Node-only (T-MOD-03e). A buggy Bun-specific resolver path that tied helper resolution to delegation could regress only on Bun and pass the existing T-MOD-03e Node coverage. Same fixture and same assertion structure as T-MOD-03e (project-root stub at `/tmp/project/node_modules/loopx/` exporting a deterministic `output()` that writes a sentinel marker and emits `{ stop: true, result: "from-project-root-stub" }` to stdout, no project-root `package.json` declaring `loopx`, no workflow-local `node_modules/loopx`, `.loopx/ralph/index.ts` doing `import { output } from "loopx"; output({ result: "from-stub" })`), but invoke loopx via the Bun runtime (e.g., `bun /abs/path/to/dist/cli.js run -n 1 ralph` or the project's standard Bun-CLI entry, mirroring T-INST-GLOBAL-01a's Bun-driver pattern) and assert the same outcomes: (a) the CLI exits 0 with the stub's `stop: true` halting the loop on the first iteration, (b) no delegation occurred (verify via the same marker pattern as T-MOD-03e), (c) the marker file `marker-resolved-stub.txt` exists with content `"from-project-root-stub"`. The Bun-side hazard is symmetric to T-MOD-03e's Node-side hazard: a programmatic driver that imported `"loopx"` would itself walk up to the project-root stub and break before the spawned script ran, so this test must drive via the CLI. **Conditional on Bun being available in the test environment** (gated like other `[Bun]` tests). `[Bun]` *(Spec 3.3, 3.2, 7.1)*
+- **T-MOD-03f**: Intermediate-ancestor `node_modules/loopx` wins over CLI fallback — proves the resolver performs a standard ancestor walk-up rather than only checking workflow-local and project-root locations. SPEC 3.3 "Resolution precedence" requires standard file-relative resolution from the importing module's path; that resolution walks up the full ancestor chain, not just two pinned locations (workflow-local, project-root). T-MOD-03a covers the workflow-local position (`.loopx/ralph/node_modules/loopx`); T-MOD-03e covers the project-root position (`node_modules/loopx`); but neither exercises an **intermediate** ancestor between the two — for example `.loopx/node_modules/loopx`. A buggy resolver that special-cased only the workflow-local and project-root positions (e.g., a hard-coded two-step lookup) would pass T-MOD-03a and T-MOD-03e but fail this case, leaving SPEC 3.3's "standard file-relative resolution" requirement under-tested. Set up: (a) a project at `/tmp/project/` with **no** project-root `package.json` declaring `loopx`; (b) install an **intermediate** stub at `/tmp/project/.loopx/node_modules/loopx/` — a marker-only stub with the same shape as T-MOD-03e's project-root stub: its `package.json` declares `{ "name": "loopx", "type": "module", "main": "./index.js" }`, and its `index.js` exports a deterministic `output(value)` that (i) writes a fixed sentinel `"from-intermediate-stub"` to a marker file at `$LOOPX_PROJECT_ROOT/marker-resolved-stub.txt`, (ii) writes `JSON.stringify({ stop: true, result: "from-intermediate-stub" }) + "\n"` to `process.stdout`, and (iii) calls `process.exit(0)`; (c) **no** workflow-local `node_modules/loopx` at `/tmp/project/.loopx/ralph/node_modules/loopx/`; (d) **no** project-root `node_modules/loopx` at `/tmp/project/node_modules/loopx/`; (e) `.loopx/ralph/index.ts` containing `import { output } from "loopx"; output({ result: "from-stub" });`. **Drive the run via the CLI** (same rationale as T-MOD-03e: a programmatic driver that imported `"loopx"` would itself walk up to the intermediate stub and break before the spawned script ran). Invoke `loopx run -n 1 ralph` against `/tmp/project/` as cwd. Assert: (a) the CLI exits 0 with the stub's `{ stop: true, result: "from-intermediate-stub" }` halting the loop on the first iteration, (b) no delegation occurred (verify via the same marker pattern as T-MOD-03e — absence of a delegation-side marker), (c) the marker file `marker-resolved-stub.txt` exists with content exactly `"from-intermediate-stub"` — proving the spawned script's `import "loopx"` resolved to the intermediate `.loopx/node_modules/loopx/` stub rather than walking past it to the (absent) project-root stub or to the CLI fallback. The walk-up path is `/tmp/project/.loopx/ralph/index.ts` → check `/tmp/project/.loopx/ralph/node_modules/loopx` (absent) → check `/tmp/project/.loopx/node_modules/loopx` (**present, wins**) → would have continued to `/tmp/project/node_modules/loopx` (absent) → CLI fallback (skipped because intermediate won). A buggy two-step resolver (workflow-local then project-root then CLI) would skip the intermediate ancestor and fall through to the CLI fallback, producing a non-zero exit (no `stop: true` from the CLI's own `output()`) or a missing marker — failing assertions (a) and (c). `[Node]` *(Spec 3.3, 3.2, 7.1)*
+- **T-MOD-03f-bun**: `[Bun]` Intermediate-ancestor `node_modules/loopx` wins over CLI fallback under Bun. Bun counterpart to T-MOD-03f. SPEC 3.3's standard file-relative precedence applies to **both** runtimes — workflow-local-vs-CLI is covered for Bun by T-MOD-02 / T-MOD-03e-bun, but the intermediate-ancestor case is currently Node-only via T-MOD-03f. A buggy Bun-specific resolver that hard-coded only workflow-local and project-root positions could regress only on Bun and pass the existing Node-side T-MOD-03f. Same fixture as T-MOD-03f (intermediate stub at `/tmp/project/.loopx/node_modules/loopx/` exporting a deterministic `output()` that writes the `"from-intermediate-stub"` sentinel and emits `{ stop: true, result: "from-intermediate-stub" }` to stdout, no project-root `package.json` declaring `loopx`, no workflow-local or project-root `node_modules/loopx`, `.loopx/ralph/index.ts` doing `import { output } from "loopx"; output({ result: "from-stub" })`), but invoke loopx via Bun (e.g., `bun /abs/path/to/dist/cli.js run -n 1 ralph` or the project's standard Bun-CLI entry, mirroring T-MOD-03e-bun's Bun-driver pattern). Assert the same outcomes as T-MOD-03f: (a) the CLI exits 0 with the stub's `stop: true` halting the loop on the first iteration, (b) no delegation occurred, (c) the marker file `marker-resolved-stub.txt` exists with content exactly `"from-intermediate-stub"`. **Conditional on Bun being available in the test environment** (gated like other `[Bun]` tests). `[Bun]` *(Spec 3.3, 3.2, 7.1)*
+- **T-MOD-03g**: Module resolution is independent of the importing script's runtime cwd — `process.chdir()` after script start does not redirect `import "loopx"` to a `node_modules/loopx` under the new cwd. SPEC 3.3 "Resolution precedence" explicitly says: "Standard file-relative resolution of `\"loopx\"` from the importing module's path always wins ... This precedence is independent of cwd." T-MOD-03a / T-MOD-03b / T-MOD-03e / T-MOD-03f cover various positional resolutions but assume a stable cwd; none exercises a script that changes cwd before importing. A buggy implementation that passed cwd into the resolver (rather than the importing module's path) would re-derive the search path from the new cwd and resolve a `node_modules/loopx` under an unrelated directory. Set up: (a) a project at `/tmp/project/` with **no** project-root or workflow-local `node_modules/loopx`; (b) an **unrelated** decoy directory at `/tmp/decoy/` containing `node_modules/loopx/` — a stub with the same shape as T-MOD-03e's project-root stub but with a distinct sentinel `"from-decoy-stub"` (its `output()` writes `"from-decoy-stub"` to `$LOOPX_PROJECT_ROOT/marker-resolved-stub.txt` and emits `{ stop: true, result: "from-decoy-stub" }` to stdout). The decoy lives outside the project's ancestor chain — `/tmp/decoy/` is **not** an ancestor of `/tmp/project/.loopx/ralph/index.ts`, so a SPEC-conformant ancestor-walk resolver would never find it; (c) `.loopx/ralph/index.ts` containing: `process.chdir("/tmp/decoy"); const { output } = await import("loopx"); output({ result: "from-stub" });` — i.e., the script changes cwd to the decoy directory **before** the dynamic import, so a buggy cwd-based resolver would resolve `"loopx"` under `/tmp/decoy/node_modules/loopx/`. **Drive the run via the CLI** (same rationale as T-MOD-03e — a programmatic driver that imports `"loopx"` could itself walk up unexpected ancestors). Invoke `loopx run -n 1 ralph` against `/tmp/project/` as cwd. Assert: (a) **the marker file `/tmp/project/marker-resolved-stub.txt` does NOT contain `"from-decoy-stub"`** — if it does, the resolver picked up the decoy `node_modules/loopx/` based on the script's runtime cwd, violating SPEC 3.3's "independent of cwd" rule. (b) Either the run completes via the CLI's own `output()` implementation (no marker file written, or marker contains the CLI's own sentinel if any) and the script's `output({ result: "from-stub" })` produces a `result: "from-stub"` Output that's parsed normally — proving `import "loopx"` resolved to the implementation under test, not the decoy. (c) The CLI exits 0 (the script ran, emitted a valid Output, and the loop completed within `-n 1`). A buggy implementation that used `process.cwd()` as the resolver root would resolve to the decoy stub and fail (a). T-MOD-03f covers the **forward** case where an intermediate ancestor wins; this test covers the **negative** case where a non-ancestor `node_modules/loopx` reachable via runtime cwd must NOT win. `[Node]` *(Spec 3.3)*
+- **T-MOD-03g-bun**: `[Bun]` Module resolution is independent of the importing script's runtime cwd — Bun counterpart to T-MOD-03g. SPEC 3.3's "independent of cwd" rule applies to **both** runtimes, and Node and Bun may use different resolver mechanics (Node's `module.register()` / standard ESM resolver vs. Bun's NODE_PATH-based resolver), so a cwd-coupling bug could regress on one runtime without affecting the other. Same fixture and assertion structure as T-MOD-03g (decoy `/tmp/decoy/node_modules/loopx/` outside the project's ancestor chain, workflow script does `process.chdir("/tmp/decoy")` before `await import("loopx")`, marker assertion must NOT contain `"from-decoy-stub"`), but invoke loopx via Bun. **Conditional on Bun being available in the test environment** (gated like other `[Bun]` tests). `[Bun]` *(Spec 3.3)*
+- **T-MOD-03h**: A nested helper module's `import "loopx"` resolves from the **helper's own file path** — not from the entry script's path, the project root, or cwd. SPEC 3.3 specifies "standard file-relative resolution of `\"loopx\"` from the importing module's path"; "importing module" is the file that contains the `import` statement, not the entry script that initiated the call chain. T-MOD-03a (workflow-local), T-MOD-03e (project-root), and T-MOD-03f (intermediate ancestor) all cover ancestor walk-up positions reachable from the **entry script's** path. None covers a helper module deeper than the entry, so a buggy implementation that hard-coded the resolver root to the entry script's directory (or to the workflow directory) would pass T-MOD-03a / T-MOD-03e / T-MOD-03f yet fail to find a `node_modules/loopx` that lives only on the helper's deeper ancestor chain. Set up: (a) a project at `/tmp/project/` with **no** project-root, workflow-local, or intermediate `node_modules/loopx` (no stub at `/tmp/project/node_modules/loopx/`, none at `/tmp/project/.loopx/node_modules/loopx/`, none at `/tmp/project/.loopx/ralph/node_modules/loopx/`); (b) `.loopx/ralph/index.ts` containing only `import "./lib/helper.ts"; import { output } from "loopx"; output({ result: "from-entry" });` — the entry script imports the nested helper first by its actual `.ts` extension (rather than the TypeScript `.js`-specifier convention, which relies on tsx / Bun extension remapping behavior that SPEC does not specify; SPEC 3.3's rule is about file-relative resolution from the importing module's path, not TS extension substitution), then imports `loopx` itself (this entry-script-side `import "loopx"` is not the test subject; it merely keeps the entry script syntactically valid and resolves through whatever path the entry can reach — typically the CLI fallback, since no entry-side ancestor `node_modules/loopx` exists); (c) `.loopx/ralph/lib/helper.ts` containing `import { output } from "loopx"; output({ stop: true, result: "from-nested-helper-stub" });` — the helper's `import "loopx"` is the test subject, and its top-level call to `output()` runs at module-import time, before the entry script's own `output()` call; (d) a **nested-helper stub** at `/tmp/project/.loopx/ralph/lib/node_modules/loopx/` — a marker-only stub with the same shape as T-MOD-03e's project-root stub. Its `package.json` declares `{ "name": "loopx", "type": "module", "main": "./index.js" }`. Its `index.js` exports a deterministic `output(value)` function that (i) writes a fixed sentinel `"from-nested-helper-stub"` to a marker file at `$LOOPX_PROJECT_ROOT/marker-resolved-stub.txt`, (ii) writes `JSON.stringify({ stop: true, result: "from-nested-helper-stub" }) + "\n"` to `process.stdout`, and (iii) calls `process.exit(0)`. **Drive the run via the CLI** (same rationale as T-MOD-03e — a programmatic driver that imports `"loopx"` could itself walk up unexpected ancestors before the spawned script ever runs). Invoke `loopx run -n 1 ralph` against `/tmp/project/` as cwd. Assert: (a) the CLI exits 0 — the nested helper's stub-side `{ stop: true, result: "from-nested-helper-stub" }` halts the loop on the first iteration (the entry script's own `output()` call never runs because the helper called `process.exit(0)` first), (b) no delegation occurred (verify via the same marker pattern as T-MOD-03e — absence of a delegation-side marker), (c) the marker file `/tmp/project/marker-resolved-stub.txt` exists with content exactly `"from-nested-helper-stub"` — proving the helper's `import "loopx"` walked up from `/tmp/project/.loopx/ralph/lib/` and found `/tmp/project/.loopx/ralph/lib/node_modules/loopx/` rather than walking from the entry script's directory `/tmp/project/.loopx/ralph/` (which would have skipped the deeper `lib/node_modules/` location and fallen through to the CLI fallback). The walk-up path for `helper.ts` is `/tmp/project/.loopx/ralph/lib/helper.ts` → check `/tmp/project/.loopx/ralph/lib/node_modules/loopx` (**present, wins**) → would have continued upward only if absent. A buggy resolver keyed off the entry script's path would walk `/tmp/project/.loopx/ralph/` (no `node_modules/loopx`) → `/tmp/project/.loopx/` (no) → `/tmp/project/` (no) → CLI fallback, never visiting `lib/node_modules/loopx/`, and would produce a different exit/marker outcome. T-MOD-03a / T-MOD-03e / T-MOD-03f cover the entry-script-importing-path axis; this test covers the **deeper-helper-importing-path** axis explicitly. `[Node]` *(Spec 3.3)*
+- **T-MOD-03h-bun**: `[Bun]` A nested helper module's `import "loopx"` resolves from the helper's own file path under Bun. Bun counterpart to T-MOD-03h. SPEC 3.3's "importing module's path" rule applies to **both** runtimes; Node and Bun may walk ancestor chains via different mechanics, so a helper-vs-entry resolver-root bug could regress on one runtime without affecting the other. Same fixture and assertion structure as T-MOD-03h (nested-helper stub at `/tmp/project/.loopx/ralph/lib/node_modules/loopx/`, no stubs at workflow-local, intermediate, or project-root positions, entry script imports `./lib/helper.ts` — by its actual `.ts` extension, not the TypeScript `.js`-specifier convention that depends on tsx / Bun extension remapping behavior outside SPEC's scope — which imports `loopx` and stops the loop with the `"from-nested-helper-stub"` sentinel), but invoke loopx via Bun. **Conditional on Bun being available in the test environment** (gated like other `[Bun]` tests). `[Bun]` *(Spec 3.3)*
 
 #### `output()` Function
 
@@ -1060,6 +2025,7 @@ All env file parsing tests below use `writeEnvFileRaw` to write exact file conte
 - **T-MOD-12**: `output(true)`. Yielded Output has `result: "true"`. *(Spec 6.4)*
 - **T-MOD-13**: `output({ result: "x", goto: undefined })`. Yielded Output has `result: "x"` and no `goto` property. *(Spec 6.4)*
 - **T-MOD-13a**: `output([1, 2, 3])` (array, no known fields). Script crashes. *(Spec 6.4)*
+- **T-MOD-13a2**: `output()` accepts an array that carries a known field set as a non-index own property. Per Spec 6.4, arrays are objects for `output()` purposes (`typeof [] === 'object'`) and are valid when they contain at least one known field with a defined value. Script: `const a: any[] = []; a.result = "ok"; output(a);`. Observe via `runPromise("ralph", { maxIterations: 1 })`: the yielded Output has `result: "ok"` (no `goto`, no `stop`). Assert exit 0. The positive case proves `output()` does not reject all arrays — only arrays without any known field, as covered in T-MOD-13a. An implementation that rejects arrays outright (e.g., via an early `Array.isArray()` guard) would pass T-MOD-13a but fail here. *(Spec 6.4)*
 - **T-MOD-13b**: `output({ result: undefined, goto: undefined, stop: undefined })`. Equivalent to `output({})`. Script crashes. *(Spec 6.4)*
 - **T-MOD-13c**: `output({ foo: "bar" })`. Script crashes (no known fields). *(Spec 6.4)*
 - **T-MOD-13d**: `output({ stop: false })`. Output accepted, but parsed as `{}` (stop must be exactly true). Loop continues. *(Spec 6.4, 2.3)*
@@ -1075,6 +2041,7 @@ All env file parsing tests below use `writeEnvFileRaw` to write exact file conte
 - **T-MOD-13n**: JS/TS `output()` does not validate name-pattern violations in bare goto targets. Script calls `output({ goto: "bad.name" })`. The script exits 0 (`output()` serializes without validation). Observe via `run("test")`: the first yielded Output has `goto: "bad.name"`, then the generator throws at transition time (invalid bare target — the dot violates the name restriction `[a-zA-Z0-9_][a-zA-Z0-9_-]*`). T-MOD-13h–13l cover invalid colon shapes and T-MOD-13m covers a syntactically valid but nonexistent target; this test covers name-pattern violations, which are a distinct validation category. A `output()` that incorrectly regex-validates names at serialization time would fail here. This mirrors CLI-helper T-SUB-02i. *(Spec 6.4)*
 - **T-MOD-13o**: JS/TS `output()` does not validate name-pattern violations in the workflow portion of a qualified goto target. Script calls `output({ goto: "bad.name:index" })`. The script exits 0. Observe via `run("test")`: the first yielded Output has `goto: "bad.name:index"`, then the generator throws at transition time (workflow-portion name violates the name restriction pattern). This is the qualified-target counterpart to T-MOD-13n and mirrors CLI-helper T-SUB-02j. *(Spec 6.4)*
 - **T-MOD-13p**: JS/TS `output()` does not validate name-pattern violations in the script portion of a qualified goto target. Script calls `output({ goto: "ralph:bad.name" })`. The script exits 0. Observe via `run("test")`: the first yielded Output has `goto: "ralph:bad.name"`, then the generator throws at transition time (script-portion name violates the name restriction pattern). Combined with T-MOD-13o, this proves that name-pattern validation is deferred for both portions of qualified targets. This mirrors CLI-helper T-SUB-02k. *(Spec 6.4)*
+- **T-MOD-13q**: `output({ result: undefined, goto: "next" })` — one known field with `undefined` value alongside another known field with a defined value. SPEC 6.4 / 2.3 say `output()` is valid when at least one known field has a defined value, and that fields with `undefined` are dropped. T-MOD-13 covers `{ result: "x", goto: undefined }` (defined `result`, undefined `goto`) → yielded Output has `result: "x"` only; T-MOD-13b covers all-`undefined` (`{ result: undefined, goto: undefined, stop: undefined }`) → script crashes. The complementary case — undefined `result` alongside a defined `goto` — is not currently pinned down, but a buggy implementation could plausibly special-case "leading known field is undefined" to a different outcome (e.g., crash, or silently swallow the entire object) than "trailing known field is undefined." Set up `.loopx/test/index.ts` calling `output({ result: undefined, goto: "next" })` and a sibling `.loopx/test/next.ts` that emits `{ stop: true }`. Observe via `runPromise("test", { maxIterations: 2 })`: assert the first yielded Output has `goto: "next"` and **no `result` property** (undefined fields are dropped, not preserved as `undefined`), and the loop transitions to `next` (the second yielded Output is from `test:next`). Together with T-MOD-13 (defined-result + undefined-goto) and T-MOD-13b (all-undefined-crash), this completes the field-presence matrix at the `output()` helper layer. Fuzz coverage likely catches this incidentally, but pinning the case down explicitly closes a manual-traceability gap. *(Spec 6.4, 2.3)*
 - **T-MOD-14**: Code after `output()` does not execute. *(Spec 6.4)*
 - **T-MOD-14a**: Large-payload flush: `output({ result: "x".repeat(1_000_000) })`. Full 1 MB string preserved. *(Spec 6.4)*
 
@@ -1087,7 +2054,9 @@ All env file parsing tests below use `writeEnvFileRaw` to write exact file conte
 
 #### ESM-Only Package Contract
 
-- **T-MOD-22**: `[Node]` `require("loopx")` from a CJS consumer fails with ERR_REQUIRE_ESM. *(Spec 1)*
+- **T-MOD-22**: The published loopx package's shape is ESM-only — the package contract does not expose a public CommonJS entry point. SPEC 1 declares loopx ESM-only, but modern Node has shipped `require(esm)` support that, depending on Node version and package shape, can allow `require("<esm-pkg>")` to succeed at runtime even for an ESM-only package. The runtime outcome of `require("loopx")` is therefore **not** a reliable cross-version conformance surface and must not be the assertion target. Instead, assert the package-shape contract that SPEC 1's "ESM-only" statement actually constrains — read the published `loopx` package's `package.json` from `node_modules/loopx/` (or the equivalent installed/test-fixture location) and assert: (a) the top-level `"type"` field equals `"module"` (so all bare `.js` entries in the package are interpreted as ESM); (b) the `"main"` field, if present, points at an `.mjs` file or at a `.js` file under a `"type": "module"` package — and **not** at a `.cjs` file or at a CJS-compatible JS file; and (c) the `"exports"` field, if present, does not declare a `"require"` condition for any public subpath (e.g., the public `"."` export must not have `{ "require": "..." }` — only `"import"` / `"default"` conditions for ESM consumers). These three conditions are the package-shape consequences of "ESM-only" that hold regardless of the consuming runtime's `require(esm)` behavior. The historical assertion ("`require('loopx')` exits non-zero with an ESM-related error message") is **not used** because Node's CJS-requires-ESM behavior has shifted across versions and a SPEC-conforming implementation that ships an ESM-only package may still see `require('loopx')` return a usable namespace under `require(esm)`-capable Node — the failure mode is a property of the consuming runtime, not of the package's "ESM-only" contract. *(Spec 1)*
+- **T-MOD-22a**: Package metadata — `name` field is exactly `"loopx"`. SPEC 1 declares "**Package name:** `loopx`"; this test pins down the published package's `name` field. Read the published `loopx` package's `package.json` (from `node_modules/loopx/` or the test-fixture install path) and assert the top-level `"name"` field is exactly the string `"loopx"` (no scope prefix like `@org/loopx`, no dash variants). A rename of the published package — deliberate or accidental — would change every `import "loopx"` resolution path across the ecosystem; pinning the name at the test layer protects the SPEC 1 declaration from silent drift. *(Spec 1)*
+- **T-MOD-22b**: Package metadata — `engines.node` (if declared) advertises Node ≥ 20.6. SPEC 1 declares "**Target runtimes:** Node.js ≥ 20.6, Bun ≥ 1.0", with a `module.register()` rationale tied to the 20.6 floor. If the published `package.json` declares an `"engines"` field (this is conventional for Node packages but not strictly required by SPEC 1), assert: (a) the `"engines.node"` range, when present, is satisfied by `20.6.0` **and** is satisfied by the oldest CI-matrix Node version (T-RUNTIME-MATRIX row for Node 20.6), **and** is not satisfied by Node 18.x or 20.5.x (so the declared floor matches SPEC 1's `>=20.6`). Use `semver.satisfies` for the range checks. If the `package.json` does not declare `"engines"` at all, the assertion is vacuously satisfied (the field is optional); the test passes with a note that no engines constraint was declared. An implementation that advertised `"engines": { "node": ">=18" }` — an obvious regression against the SPEC 1 `module.register()` requirement — would fail this test. `[Node]` *(Spec 1)*
 
 #### `LOOPX_BIN` in Bash Scripts
 
@@ -1095,6 +2064,7 @@ All env file parsing tests below use `writeEnvFileRaw` to write exact file conte
 
 - **T-MOD-19**: Bash script uses `$LOOPX_BIN output --result "payload" --goto "reader"`. Assert the reader script receives `"payload"` via stdin. *(Spec 3.4)*
 - **T-MOD-20**: Bash script writes `$LOOPX_BIN` to a marker file. Assert it contains a valid executable path. *(Spec 3.4)*
+- **T-MOD-20a**: Non-delegated `LOOPX_BIN` is the resolved realpath, not the symlink path. SPEC 3.2 / 8.3 define `LOOPX_BIN` as "**Resolved realpath** of the effective loopx binary (post-delegation)". T-DEL-05 pins this down for the delegated case; this test closes the non-delegated (global) case. Set up a fixture with **no project-root `package.json`** (so delegation is skipped — the global binary handles the invocation). Place the real global loopx launcher at a real path (e.g., `/tmp/real-prefix/bin/loopx-real`) and create a symlink to it at `/tmp/link-prefix/bin/loopx` (a symlinked global launcher, the common `npm -g` install pattern). Invoke loopx through the symlinked path: `/tmp/link-prefix/bin/loopx run ralph`. `.loopx/ralph/index.sh` writes `$LOOPX_BIN` to a marker file. Assert: (a) exit code 0, (b) the marker file contains `/tmp/real-prefix/bin/loopx-real` — the realpath-resolved target, not `/tmp/link-prefix/bin/loopx` (the symlink invocation path) and not `$PATH`-relative. A buggy implementation that reported `argv[0]` or `process.execPath` without `realpath` resolution would fail this assertion. Uses `withDelegationSetup` (or an equivalent real-filesystem fixture), not `runCLI`, because `runCLI`'s `node /path/to/bin.js` invocation short-circuits the symlink-resolution path. *(Spec 3.2, 3.4, 8.3)*
 - **T-MOD-21**: Bash script runs `$LOOPX_BIN version` and captures stdout. Assert it matches the package version. *(Spec 3.4)*
 - **T-MOD-21a**: End-to-end bash cross-workflow goto via `$LOOPX_BIN output`. Create two workflows: `.loopx/alpha/index.sh` (runs `$LOOPX_BIN output --goto "beta:index"`) and `.loopx/beta/index.sh` (writes `"arrived"` to a marker file via `printf '%s' "arrived" > <markerPath>`, then runs `$LOOPX_BIN output --result "arrived" --stop`). Run `loopx run alpha` via CLI. Assert: (a) exit code 0 (stop: true halted the loop cleanly), and (b) the marker file exists and contains `"arrived"` (proving `beta:index` executed after the cross-workflow goto). The CLI never prints structured Output to its own stdout (Spec 7.1), so assertions use marker files and exit code, not stdout parsing. This is a composition test spanning sections 3.4 (LOOPX_BIN), 4.3 (loopx output subcommand), and 2.2 (cross-workflow goto). *(Spec 3.4, 4.3, 2.2)*
 
@@ -1112,8 +2082,10 @@ All env file parsing tests below use `writeEnvFileRaw` to write exact file conte
 - **T-API-04**: Generator completes when `maxIterations` is reached. *(Spec 9.1)*
 - **T-API-05**: The output from the final iteration is yielded before the generator completes. *(Spec 9.1)*
 - **T-API-06**: Breaking out of `for await` loop after the first yield prevents further iterations. *(Spec 9.1)*
-- **T-API-07**: `run("ralph", { cwd: "/path/to/project" })` resolves workflows relative to the given cwd. `cwd` is the **project root** — it controls where `.loopx/` is found and sets `LOOPX_PROJECT_ROOT`, but does not control the script's execution working directory (scripts always run with their workflow directory as cwd). The test must explicitly assert that `LOOPX_PROJECT_ROOT` equals the provided `cwd` value (via a marker file written by the script using `observe-env`), not just that discovery succeeded. *(Spec 9.5, 6.1)*
-- **T-API-07a**: `RunOptions.cwd` does not control script execution cwd. Create a workflow in project A. Call `run("ralph", { cwd: projectA })`. Script writes `process.cwd()` to a marker file. Assert marker equals the workflow directory path (`.loopx/ralph/`), not `projectA`. *(Spec 9.5, 6.1)*
+- **T-API-07**: `run("ralph", { cwd: "/path/to/project" })` resolves workflows relative to the given cwd. `RunOptions.cwd` sets **both** the project root (`LOOPX_PROJECT_ROOT` and the directory from which `.loopx/` is resolved) **and** the script execution cwd — per Spec 9.5 and 6.1, cwd and project root are unified. The test must assert both: (a) `LOOPX_PROJECT_ROOT` (via `observe-env`) equals the provided `cwd` value, and (b) the script's own `process.cwd()` (via `observe-cwd-ts`) reports the same directory identity (device/inode match; exact string spelling is runtime-canonicalized per Spec 6.1 "Directory identity vs. string spelling"). *(Spec 9.5, 6.1)*
+- **T-API-07a**: `RunOptions.cwd` controls script execution cwd (project-root-unified). Create a workflow in project A. Call `run("ralph", { cwd: projectA })`. Script observes its cwd via `observe-cwd-ts` (`process.cwd()`) and its `LOOPX_WORKFLOW_DIR` via `observe-env`. Assert: (a) the cwd marker matches `projectA` (not `.loopx/ralph/`) — script execution cwd equals the project root; (b) the `LOOPX_WORKFLOW_DIR` marker equals the absolute path of `projectA`'s `.loopx/ralph/` directory — the workflow-relative path is exposed via `LOOPX_WORKFLOW_DIR`, not cwd. This pins down Spec 9.5's clarification that `cwd` specifies both the project root **and** the script execution cwd, and that the previous "`cwd` does not control script execution cwd" disclaimer no longer applies. *(Spec 9.5, 6.1)*
+- **T-API-07b**: Relative `RunOptions.cwd` is resolved via `path.resolve(process.cwd(), options.cwd)` once at call time — no `realpath` / canonicalization. Per SPEC 3.2 / 9.5, a relative `cwd` is resolved lexically via `path.resolve` only, and `path.resolve` preserves symlink-spelling verbatim. Set up a real project at `/tmp/test-relative-cwd-project/`, with `.loopx/ralph/index.sh` present. From a driver running with `process.cwd() = /tmp/test-relative-cwd-project`, call `runPromise("ralph", { cwd: "./sub/../project", maxIterations: 1 })` (a relative path with a traversal component). The lexical resolution of this should equal `path.resolve("/tmp/test-relative-cwd-project", "./sub/../project")`, which is `/tmp/test-relative-cwd-project/project`. Seed that resolved path with its own `.loopx/ralph/index.sh`. Script observes `LOOPX_PROJECT_ROOT` via `observe-env`. Assert: (a) the marker equals exactly `/tmp/test-relative-cwd-project/project` (the lexically resolved absolute path), and (b) the marker does not contain any `..` components — resolution happened lexically and was captured at call time. A buggy implementation that canonicalized via `realpath` would still produce the same string here (no symlinks involved) but would fail tests that combine a symlink component (covered by T-SYM-03/T-SYM-04). This test is the relative-path counterpart to T-SYM-03/T-SYM-04 and pins down the "resolved once at call time" rule for the relative-path case specifically. *(Spec 9.5, 3.2, 6.1)*
+- **T-API-07c**: Relative `RunOptions.cwd` whose path component is a symlink preserves the symlinked spelling — no `realpath`. Per SPEC 3.2 "A relative `RunOptions.cwd` is resolved via `path.resolve(process.cwd(), options.cwd)` once at call time ... `path.resolve` is a pure string operation — symlinked components in `RunOptions.cwd` are preserved verbatim. No further `realpath` is applied", and SPEC 9.5 "A relative `cwd` is resolved via `path.resolve(process.cwd(), options.cwd)` once at call time; an absolute value is used unchanged." T-API-07b covers the lexical-resolution rule with a `..` traversal but no symlink (so a buggy `realpath` implementation would still produce the same string and pass), and T-SYM-03 / T-SYM-04 / T-SYM-04a / T-SYM-04b cover **absolute** symlinked / non-canonical `cwd` values. The combination — **relative `cwd` whose value names a symlink** — is not directly covered. A buggy implementation that called `realpath` after `path.resolve` would still pass T-API-07b (no symlink) and might pass T-SYM-03 if relative paths follow a different code path; this test closes the relative+symlink combination. Set up a real project at `/tmp/test-rel-symlink-parent/real-project/` containing `.loopx/ralph/index.sh` (observes `LOOPX_PROJECT_ROOT` via `observe-env`). Create a symlink `/tmp/test-rel-symlink-parent/link-project -> /tmp/test-rel-symlink-parent/real-project`. From a driver running with `process.cwd() = /tmp/test-rel-symlink-parent`, call `runPromise("ralph", { cwd: "link-project", maxIterations: 1 })` — a **relative** path whose value is the **symlink name**, not the realpath. Assert: (a) the promise resolves (no rejection — discovery, env-file loading, and target resolution all succeed against the symlinked spelling), (b) the `LOOPX_PROJECT_ROOT` marker is **byte-for-byte equal** to `/tmp/test-rel-symlink-parent/link-project` — the symlink-preserving spelling produced by `path.resolve("/tmp/test-rel-symlink-parent", "link-project")` (which is a pure string join, not a `realpath`-aware operation), and (c) the marker does **not** equal `/tmp/test-rel-symlink-parent/real-project` — a `realpath` call after the lexical resolve would canonicalize the symlink and fail this assertion. As a defensive supplemental assertion, also assert that the marker resolves to the same directory identity (device/inode) as `/tmp/test-rel-symlink-parent/real-project` (via `stat`), proving the symlink is intact and the test is exercising the relative+symlink path regardless of which spelling the marker captured. This is the relative-path counterpart to T-SYM-03 (absolute symlinked cwd) and pins down the SPEC 3.2 / 9.5 "no further `realpath`" rule on the relative-path resolution branch specifically — the rule must hold across all `cwd` resolution paths, not just absolute. *(Spec 3.2, 6.1, 9.5)*
 - **T-API-08**: `run("ralph", { maxIterations: 0 })` → generator completes immediately with no yields. *(Spec 9.5)*
 - **T-API-08a**: `run("nonexistent", { maxIterations: 0 })` → generator throws on first `next()` (validation runs before zero-iteration short-circuit). *(Spec 9.1, 9.5, 7.1)*
 - **T-API-08b**: `runPromise("ralph", { maxIterations: 0 })` skips workflow-level version checking, mirroring CLI `-n 0`. Set up `.loopx/ralph/` with `package.json` declaring a loopx version range not satisfied by the running version. Assert: (a) resolves with `[]`, and (b) no version mismatch warning on stderr. *(Spec 9.5, 3.2)*
@@ -1127,7 +2099,10 @@ All env file parsing tests below use `writeEnvFileRaw` to write exact file conte
 - **T-API-08j**: `run("ralph", { maxIterations: 0 })` with `.loopx/` containing a sibling workflow with an invalid workflow name (e.g., `.loopx/-bad-workflow/index.sh`) → generator throws on first `next()`. Global discovery validation catches the invalid workflow name before the zero-iteration short-circuit, mirroring CLI `-n 0` behavior (T-CLI-22e). *(Spec 9.1, 9.5, 5.3)*
 - **T-API-08k**: `run("ralph", { maxIterations: 0, envFile: "malformed.env" })` where `malformed.env` exists and is readable but contains an invalid line (e.g., `1BAD=val`) → generator completes with no yields, stderr contains a parser warning for the invalid key. Env files are parsed under `maxIterations: 0`, not just existence-checked, mirroring CLI `-n 0` behavior (T-CLI-22c). *(Spec 9.1, 9.5, 8.1)*
 - **T-API-08l**: `run("ralph", { maxIterations: 0 })` with an unreadable global env file → generator throws on first `next()`. Global env loading and validation fires before the zero-iteration short-circuit, mirroring CLI `-n 0` behavior (T-ENV-25b). **Conditional on `process.getuid() !== 0`.** *(Spec 9.1, 9.5, 8.1)*
+- **T-API-08l2**: `runPromise("ralph", { maxIterations: 0 })` with an unreadable global env file → rejects. This is the `runPromise()` twin of T-API-08l, providing generator/promise symmetry for the unreadable global env file case under `maxIterations: 0` and the `runPromise()` counterpart to CLI T-ENV-25b. T-API-08l covers the `run()` surface and T-ENV-25b covers the CLI surface; without this test, `runPromise()` has no coverage of the unreadable-global-env failure path. **Conditional on `process.getuid() !== 0`.** *(Spec 9.2, 9.5, 8.1)*
 - **T-API-08m**: `run("ralph", { maxIterations: 0 })` with a malformed-but-readable global env file (e.g., containing `1BAD=val`) → generator completes with no yields, stderr contains a parser warning for the invalid key. Global env files are parsed under `maxIterations: 0` in the programmatic API, mirroring CLI `-n 0` behavior (T-ENV-25c). *(Spec 9.1, 9.5, 8.1)*
+- **T-API-08k2**: `runPromise("ralph", { maxIterations: 0, envFile: "malformed.env" })` where `malformed.env` exists and is readable but contains an invalid line (e.g., `1BAD=val`) → **promise resolves with an empty array `[]`** (no yields since zero iterations), stderr contains a parser warning for the invalid key. This is the `runPromise()` twin of T-API-08k (`run()` surface), providing promise-surface symmetry for the malformed-local-envFile parse-warning-under-`maxIterations: 0` case. Env files are parsed under `maxIterations: 0` on the promise surface just as on the generator surface, mirroring CLI `-n 0` behavior (T-CLI-22c). A buggy implementation that resolved `[]` without actually reading the env file under `maxIterations: 0` would fail this test (missing warning on stderr); an implementation that rejected the promise rather than resolving with `[]` would also fail (malformed-but-readable env files are non-fatal per SPEC 8.1 — invalid lines are ignored with a warning, not treated as a parse error). *(Spec 9.2, 9.5, 8.1, 8.2)*
+- **T-API-08m2**: `runPromise("ralph", { maxIterations: 0 })` with a malformed-but-readable global env file (e.g., containing `1BAD=val` in `$XDG_CONFIG_HOME/loopx/env` via `withGlobalEnv`) → **promise resolves with an empty array `[]`**, stderr contains a parser warning for the invalid key. This is the `runPromise()` twin of T-API-08m (`run()` surface), providing promise-surface symmetry for the malformed-global-env-file parse-warning-under-`maxIterations: 0` case. Global env files are parsed under `maxIterations: 0` on the promise surface. Together with T-API-08k (run + local), T-API-08k2 (runPromise + local), T-API-08m (run + global), this closes the `maxIterations: 0` env-parser-warning parity matrix across both programmatic surfaces and both env-file scopes — matching the CLI-surface coverage (T-CLI-22c local, T-ENV-25c global). *(Spec 9.2, 9.5, 8.1)*
 - **T-API-08n**: `runPromise("a:b:c", { maxIterations: 0 })` → rejects. Malformed target strings (multiple colons) are validated before the `maxIterations: 0` short-circuit, mirroring CLI `-n 0` behavior (T-CLI-119d). This extends the `maxIterations: 0` validation coverage (T-API-08a/08c/08d test missing workflow/index/script) to cover target-syntax validation. *(Spec 9.2, 9.5, 4.1)*
 - **T-API-08n1**: `run("a:b:c", { maxIterations: 0 })` returns a generator (lazy); on the first `next()`, the generator throws an invalid-target error. Malformed target strings (multiple colons) are validated before the `maxIterations: 0` short-circuit on the generator surface, mirroring CLI `-n 0` behavior (T-CLI-119d) and the `runPromise` surface (T-API-08n). This is the `run()` generator counterpart to T-API-08n, completing target-syntax validation parity under `maxIterations: 0` across all three surfaces (CLI, `run()`, `runPromise()`). ADR-0003 changed target syntax and zero-iteration semantics enough that the ordering rule — validate target syntax before zero-iteration skip — must be pinned down on the generator API independently of the promise API. *(Spec 9.1, 9.5, 4.1)*
 - **T-API-08o**: `run("ralph", { maxIterations: 0 })` with `.loopx/ralph/package.json` unreadable (e.g., mode 000) → generator completes with no yields and no `package.json` warning on stderr. This extends T-API-08b (unsatisfied range via `runPromise`) and T-API-08g (invalid semver via `run()`) to the unreadable-file failure path — completing coverage of all three distinct `package.json` failure branches in SPEC 3.2 under `maxIterations: 0`. Mirrors CLI behavior (T-CLI-119e). **Conditional on `process.getuid() !== 0`.** *(Spec 9.1, 9.5, 3.2)*
@@ -1173,8 +2148,8 @@ All env file parsing tests below use `writeEnvFileRaw` to write exact file conte
 - **T-API-35a**: `run("-bad:index")` (workflow name violates name restrictions). Fixture contains a valid `.loopx/ralph/index.sh`. On first `next()`, throws. Assert the error references the name restriction violation. *(Spec 9.1, 4.1)*
 - **T-API-35b**: `run("ralph:-bad")` (script name violates name restrictions). Fixture contains a valid `.loopx/ralph/index.sh`. On first `next()`, throws. Assert the error references the name restriction violation. *(Spec 9.1, 4.1)*
 - **T-API-35d**: `run("bad.name")` (bare target where the workflow name violates name restrictions). Fixture contains a valid `.loopx/ralph/index.sh`. On first `next()`, throws. Assert the error references the name restriction violation. This is the bare-name counterpart to T-API-35a (qualified target with invalid workflow name). *(Spec 9.1, 4.1)*
-- **T-API-35c**: Invalid target format is rejected after discovery and global validation in the programmatic API, mirroring CLI T-CLI-114a. Create `.loopx/broken/check.sh` and `.loopx/broken/check.ts` (name collision) alongside `.loopx/valid/index.sh`. Call `run(":script")` — generator is returned (lazy). On first `next()`, the generator throws. Assert that the error mentions the name collision in `broken` — proving discovery and global validation ran before the invalid target format was rejected. *(Spec 9.1, 4.1, 5.4)*
-- **T-API-35f**: Invalid target with a name-restriction violation is rejected after discovery and global validation in `run()`, mirroring CLI T-CLI-118b. Create `.loopx/broken/check.sh` and `.loopx/broken/check.ts` (name collision) alongside `.loopx/valid/index.sh`. Call `run("bad.name")` (bare target whose workflow-name portion contains `.`, violating the name restriction pattern `[a-zA-Z0-9_][a-zA-Z0-9_-]*`) — generator is returned (lazy). On first `next()`, the generator throws. Assert that the error mentions the name collision in `broken` — proving discovery and global validation ran before the invalid bare target name was rejected. T-API-35c covers the ordering proof for malformed colon-shape targets (`":script"`) in `run()`; this test covers the same ordering proof for the name-restriction invalid-target category, a distinct validation path under ADR-0003's expanded target validation rules. Per Spec 4.1/9.1, invalid targets are rejected "at the same point as a missing workflow (after discovery, or lazily on first iteration for the API)." *(Spec 9.1, 4.1, 5.4)*
+- **T-API-35c**: `run(":script")` in a fixture with a sibling name-collision (`.loopx/broken/check.sh` + `.loopx/broken/check.ts` alongside `.loopx/valid/index.sh`) returns a generator (lazy) and throws on first `next()`. Do **not** assert which pre-iteration error wins: SPEC 4.1 says the programmatic API surfaces invalid-target errors lazily on first iteration, and "relative ordering against other pre-iteration failures is implementation-defined except for the pinned option-error and abort-precedence rules in section 9.3." This test exists to pin down lazy surfacing on the mixed-failure-fixture surface, not to mirror CLI T-CLI-114a's ordering guarantee (which is CLI-only). *(Spec 9.1, 4.1)*
+- **T-API-35f**: `run("bad.name")` (bare target whose workflow-name portion contains `.`, violating the name restriction pattern `[a-zA-Z0-9_][a-zA-Z0-9_-]*`) in a fixture with a sibling name-collision (`.loopx/broken/check.sh` + `.loopx/broken/check.ts` alongside `.loopx/valid/index.sh`) returns a generator (lazy) and throws on first `next()`. Do **not** assert whether the name-restriction error or the sibling-collision discovery error wins — per SPEC 4.1, the programmatic API leaves this ordering implementation-defined outside of the pinned section 9.3 rules. This test exists to pin down lazy surfacing in a mixed-failure fixture on the generator surface, not the ordering that CLI T-CLI-118b pins down for the CLI surface. *(Spec 9.1, 4.1)*
 
 #### `run()` Target Semantics
 
@@ -1189,13 +2164,35 @@ All env file parsing tests below use `writeEnvFileRaw` to write exact file conte
 - **T-API-09b**: `run()` cwd snapshot timing. Create two project directories: `projectA` (with `.loopx/ralph/index.sh` that writes a marker file) and `projectB` (with no `.loopx/`). Call `process.chdir(projectA)`, then `const gen = run("ralph", { maxIterations: 1 })` (no explicit `cwd`, so it captures `process.cwd()`). Call `process.chdir(projectB)` before iterating. Call `gen.next()`. Assert: the generator yields successfully using `projectA`'s workflow (marker file written), not `projectB` — proving `process.cwd()` was captured at `run()` call time, not at first iteration. *(Spec 9.1, 9.5)*
 - **T-API-09a**: Manual iterator cancellation during a pending `next()`. Assert child process terminated and generator completes. *(Spec 9.1)*
 - **T-API-09c**: `run()` options snapshot — mutating `maxIterations` after call has no effect. Set up `.loopx/ralph/index.sh` that outputs `{"result": "ok"}` (no stop/goto). `const opts = { maxIterations: 2 }; const gen = run("ralph", opts); opts.maxIterations = 1;` Iterate `gen` to completion. Assert exactly 2 outputs are yielded, not 1 — proving the options object was snapshotted at call time. *(Spec 9.1)*
+- **T-API-09d**: `.return()` after a yielded output, when no child is active, completes silently. Set up `.loopx/ralph/index.sh` that outputs `{"result":"ok"}` (no goto, no stop — the loop will reset to the starting target between iterations). Drive: `const gen = run("ralph"); const first = await gen.next(); // first script has exited (yielded, child gone); const settled = await gen.return(undefined); // no child active at this point`. Assert: (a) `first.value` is the first iteration's output, (b) `settled.done === true`, (c) the `.return()` resolves cleanly without throwing, (d) no further iterations ran (e.g., use a counter fixture to verify exactly one execution occurred). Per SPEC 9.1, when no child process is active at the time of cancellation (e.g., `break` after a yield, between iterations, or here via `.return()` after a yield), "the generator simply completes with no further yields. This is a silent, clean completion." Currently only `break` (T-API-06 / T-TMP-22) covers this branch; this test and T-API-09e extend the no-active-child cancellation coverage to `.return()` and `.throw()`. *(Spec 9.1)*
+- **T-API-09e**: `.throw()` after a yielded output, when no child is active, completes silently and does **not** surface the consumer-supplied error. Same fixture as T-API-09d (script yields `{"result":"ok"}` then exits, then loop is about to reset). Drive: `const gen = run("ralph"); const first = await gen.next(); const settled = await gen.throw(new Error("consumer-err"));` Assert: (a) `first.value` is the first iteration's output, (b) the `.throw()` resolves cleanly with `settled.done === true` rather than rejecting with the consumer error, (c) no further iterations ran. Per SPEC 9.1, `.throw()` after first `next()` is a consumer-driven cancellation surface that produces a silent, clean completion — the consumer error is not surfaced back at the caller. This pins down that "no child active" plus `.throw()` still takes the silent-completion path, not a throw-consumer-error path. Together with T-API-06 / T-TMP-22 (`break`) and T-API-09d (`.return()`), this completes no-active-child cancellation coverage across all three consumer-driven surfaces. *(Spec 9.1)*
 
 #### `run()` with AbortSignal
 
 - **T-API-10**: `run("ralph", { signal })` — aborting terminates the loop, generator throws abort error. *(Spec 9.5)*
 - **T-API-10a**: Aborting while child process is active terminates the child process group. *(Spec 9.5, 9.1)*
 - **T-API-10b**: Pre-aborted signal → generator throws on first `next()`, no child spawned. *(Spec 9.5, 9.1)*
+- **T-API-10b2**: Signal aborted **after `run()` call but before first `next()`** → first `next()` throws abort error, no child spawned, no tmpdir created. SPEC 9.1 / 9.5 specify that `options.signal` is captured at `run()` call time and applied lazily on the first iteration; T-API-10b covers the pre-aborted-at-call-time case (signal already aborted when `run()` is invoked) and T-API-10c covers the between-iterations case (signal aborted after at least one iteration has run). Neither covers the lazy-generator window between `run()` returning and first `next()` being called — a SPEC-distinct case where the signal is captured "live" (not pre-aborted) and then aborted before iteration begins. T-API-10i (Known Gap, section 4.11) describes the **separate** "abort during pre-iteration" case (abort delivered after `next()` is called but before first child spawn), which still requires a coordination seam to test deterministically; the case here is simpler — no `next()` has been called yet, so timing is fully under the test's control with no harness seam needed. Set up `.loopx/ralph/index.sh` that writes its PID to a marker file (so the test can verify no child was actually spawned) and observes `LOOPX_TMPDIR` (so the test can verify no tmpdir was created). Snapshot `os.tmpdir()` for `loopx-*` entries before the test (per the test-isolated tmpdir parent guidance from section 4.7). Drive: `const c = new AbortController(); const gen = run("ralph", { signal: c.signal, maxIterations: 1 }); c.abort(); await expect(gen.next()).rejects.toThrow(/abort/i);` Assert: (a) `gen.next()` rejects with an abort error (matching T-API-10's abort-error shape), (b) the script's PID marker file does **not** exist (no child was spawned — the abort displaced the iteration before target resolution / spawn), (c) no new `loopx-*` directory was created under the test-isolated tmpdir parent (`LOOPX_TMPDIR` was never created — per SPEC 7.1 / 9.3, abort during pre-iteration before the first child spawn displaces tmpdir creation among the other pre-iteration steps), and (d) the script's `LOOPX_TMPDIR`-observation marker file does not exist (the script never ran, so could never have observed the variable). This pins down the lazy-capture-then-abort window: an implementation that tracked abort only at iteration start (rather than capturing the signal once at call time and watching for abort throughout the lazy window) would either miss the abort or surface a different pre-iteration error first. T-API-10b uses a signal that is already aborted at the call site (so the abort precedence rule fires immediately on first `next()`); T-API-10b2 uses a signal that is live at the call site and aborts in the user-controlled window before `next()` — distinguishing "already-aborted-signal precedence" from "signal-captured-then-aborted-before-iteration precedence." Both must surface the abort error per SPEC 9.3's abort-precedence-over-pre-iteration-failures rule. *(Spec 9.5, 9.1, 9.3, 7.1, 7.4)*
 - **T-API-10c**: Signal aborted between iterations → next `next()` throws abort error. *(Spec 9.5, 9.1)*
+- **T-API-10c2**: Pre-aborted signal × `maxIterations: 0` on `runPromise()` — abort wins over the zero-iteration short-circuit. SPEC 9.1 / 9.5 specify that an `AbortSignal` aborted at call time produces an abort error even before execution, while `maxIterations: 0` normally resolves with `[]` without spawning. SPEC 9.3's "Abort precedence over pre-iteration failures" rule places abort observation ahead of every other pre-iteration mode (target validation, `.loopx/` discovery, env-file loading, target resolution, tmpdir creation) — and `maxIterations: 0`'s zero-iteration early exit is a pre-iteration short-circuit on the same logical layer. The two clauses jointly imply that an aborted signal must displace the `maxIterations: 0` short-circuit: the call must reject with the abort error rather than resolve with `[]`. Set up `.loopx/ralph/index.sh` that writes its PID to a marker file (so the test can verify no child was spawned). Snapshot the test-isolated tmpdir parent for `loopx-*` entries before the call. Drive: `const c = new AbortController(); c.abort(); const promise = runPromise("ralph", { signal: c.signal, maxIterations: 0 });` Assert: (a) the promise **rejects** with an abort error (matching T-API-10b's abort-error shape) — does **not** resolve with `[]`, (b) the script's PID marker file does not exist (no child was spawned), and (c) no new `loopx-*` directory was created under the test-isolated tmpdir parent (no tmpdir created — `maxIterations: 0` independently suppresses tmpdir creation per SPEC 7.4, and the abort precedence rule does not undo that suppression). A buggy implementation that evaluated `maxIterations: 0` before checking `options.signal.aborted` would resolve with `[]`, missing the abort and failing assertion (a). The cardinal contract is that abort observation is invariant under the iteration count — `maxIterations: 0` must not give the implementation a license to skip the abort check. *(Spec 9.5, 9.1, 9.3, 7.4)*
+- **T-API-10c3**: Pre-aborted signal × `maxIterations: 0` on `run()` — first `next()` throws abort error, no zero-iteration silent completion. Generator-surface counterpart to T-API-10c2. SPEC 9.1's pre-first-`next()` consumer-cancellation carve-out applies only to **consumer-driven** cancellation (`.return()` / `.throw()` as the first interaction), not to `AbortSignal`-driven cancellation — an aborted signal captured at call time must surface on the first `next()` regardless of the iteration count. SPEC 9.5's `maxIterations: 0` clause says "validates and exits without executing any iterations" — but "validates" must happen *after* the abort precedence check per SPEC 9.3. Same fixture (script writes PID marker; the script never runs). Drive: `const c = new AbortController(); c.abort(); const gen = run("ralph", { signal: c.signal, maxIterations: 0 }); await expect(gen.next()).rejects.toThrow(/abort/i);` Assert: (a) `gen.next()` rejects with an abort error (does **not** resolve to `{ done: true, value: undefined }` — the zero-iteration silent-completion path does not fire when the signal is aborted at call time), (b) the script's PID marker file does not exist (no child spawned), and (c) no `loopx-*` directory was created under the test-isolated tmpdir parent. T-API-10c2 covers the `runPromise()` surface; this test covers the `run()` generator surface so both API entry points are pinned down for the abort × zero-iteration interaction. A buggy implementation that short-circuited `maxIterations: 0` ahead of the abort precedence check would resolve `gen.next()` cleanly, missing the abort. *(Spec 9.5, 9.1, 9.3, 7.4)*
+- **T-API-10c4**: **Live signal that aborts after `run()` returns but before first `next()` × `maxIterations: 0` on `run()`** — first `next()` throws abort error, no zero-iteration silent completion. Companion to T-API-10c3 for the **live-abort-after-call** sub-window of SPEC 9.3's abort-precedence rule. T-API-10c3 covers the **already-aborted-at-call-time** case (signal is aborted *before* `run()` is called, so the abort listener registered at call time per T-API-64k attaches to an already-aborted signal); T-API-10b2 covers the live-abort-before-first-`next()` case under nonzero `maxIterations`. The combination — **live signal that aborts after `run()` returns × `maxIterations: 0`** — is uncovered. A buggy implementation that gated the `maxIterations: 0` short-circuit on a single `signal.aborted` snapshot taken at call time (rather than on the captured-signal abort listener firing through the lazy window) would treat a live signal as "not aborted at call time → take the zero-iteration short-circuit" and resolve `{ done: true }` cleanly even though the signal aborted before the consumer's first interaction. Set up `.loopx/ralph/index.sh` that writes its PID to a marker file (so the test can verify no child was spawned) and observes `LOOPX_TMPDIR` (so the test can verify no tmpdir was created). Snapshot the test-isolated tmpdir parent for `loopx-*` entries before the call. Drive: `const c = new AbortController(); const gen = run("ralph", { signal: c.signal, maxIterations: 0 }); /* signal is live (not aborted) at call time; the listener attached during the call-site snapshot per SPEC 9.1 */ c.abort(); /* listener fires synchronously, transitioning the captured signal to aborted */ await expect(gen.next()).rejects.toThrow(/abort/i);` Assert: (a) `gen.next()` rejects with an abort error — does **not** resolve to `{ done: true, value: undefined }` despite `maxIterations: 0`, (b) the script's PID marker file does not exist (no child spawned), and (c) no new `loopx-*` directory was created under the test-isolated tmpdir parent. This pins down that the abort listener registered at call time observes a state transition between `run()` returning and first `next()`, and that observation displaces the `maxIterations: 0` zero-iteration short-circuit on the same call. The listener must observe the live transition; an implementation that snapshotted `signal.aborted === false` at call time and then applied the zero-iteration short-circuit on first `next()` without re-checking the captured signal's `aborted` (or without arming the listener to fire through the lazy window) would fail (a). *(Spec 9.5, 9.1, 9.3, 7.4)*
+- **T-API-10c5**: **Live signal that aborts immediately after `runPromise()` returns × `maxIterations: 0`** — promise rejects with abort error, does not resolve with `[]`. `runPromise()` counterpart to T-API-10c4. SPEC 9.2 specifies that `runPromise()` snapshots `options.signal` eagerly at the call site (not lazily on first iteration) — so the captured signal's abort listener is registered before `runPromise()` returns per T-API-64k2. The combination — **live signal that aborts after `runPromise()` returns but before the promise has been awaited × `maxIterations: 0`** — is the symmetric uncovered case alongside T-API-10c4 on the promise surface. A buggy implementation that took the `maxIterations: 0` zero-iteration short-circuit synchronously inside `runPromise()` (resolving the promise with `[]` before the abort listener has a chance to fire) — or that captured the signal lazily despite SPEC 9.2's eager-capture contract — would fail the abort-precedence rule for this sub-window. Same fixture as T-API-10c4 (script writes PID marker; never runs). Snapshot the test-isolated tmpdir parent for `loopx-*` entries. Drive: `const c = new AbortController(); const promise = runPromise("ralph", { signal: c.signal, maxIterations: 0 }); /* signal live at call site; eager capture per SPEC 9.2 */ c.abort(); /* listener fires synchronously after runPromise() has returned but before the test awaits */ await expect(promise).rejects.toThrow(/abort/i);` Assert: (a) the promise **rejects** with an abort error — does **not** resolve to `[]` despite `maxIterations: 0`, (b) the script's PID marker file does not exist (no child spawned), and (c) no new `loopx-*` directory was created under the test-isolated tmpdir parent. Together with T-API-10c4 (`run()` surface), T-API-10c2 / T-API-10c3 (pre-aborted signal × `maxIterations: 0` on both surfaces), and T-API-10b2 (live-abort × nonzero `maxIterations`), this completes the abort × `maxIterations: 0` × live-vs-pre-aborted × surface matrix. *(Spec 9.5, 9.2, 9.3, 7.4)*
+
+#### Programmatic Cancellation Process-Group & SIGKILL Escalation
+
+SPEC 9.1 requires both consumer-driven cancellation (`.return()`, `.throw()`, `break`) and `AbortSignal`-driven cancellation to terminate the **active child process group** (not just the direct child) with SIGTERM and escalate to SIGKILL after a 5-second grace period — the same contract as CLI SIGINT/SIGTERM in SPEC 7.3. CLI coverage (T-SIG-05 for SIGKILL escalation, T-SIG-06 for process-group forwarding) is solid; these tests pin down the same contract on the programmatic surfaces, where T-API-10a covers process-group termination under `AbortSignal` but not grandchildren, and no existing test covers SIGKILL escalation under programmatic cancellation. All tests in this block are tagged `@flaky-retry(3)` like the CLI signal tests (T-SIG-05 / T-INST-116c) because of the real-time 5-second wait.
+
+**Driver-helper requirement.** All tests in this block require mid-run synchronization between the harness and the driver process: the harness must `waitForStderr("ready")` on the driver's stderr stream, read PIDs from fixture-supplied marker files, and then trigger an action (call `c.abort()`, call `gen.return()`, etc.) before the driver settles. This is incompatible with `runAPIDriver()` (which returns a settled `Promise`). These tests use **`runAPIDriverLive()`** (section 2.3) to obtain a driver-process handle exposing `waitForStderr` / `waitForStdout` / `waitForExit` / `pid` / `sendSignal`, then deliver the cancellation trigger via `sendSignal` (or another in-driver coordination mechanism) so the driver script can invoke `c.abort()` / `gen.return()` / `gen.throw()` from inside its own process while the harness observes from outside. Test descriptions below use `waitForStderr("ready")` shorthand to refer to this driver-handle API, not to a Vitest-process-local helper.
+
+- **T-API-10d**: `AbortSignal` terminates the active child process **group** — both child and grandchild die. Fixture: `.loopx/ralph/index.sh` spawns a long-lived background grandchild (e.g., `sleep 3600 &`), writes the grandchild PID to a marker, writes `"ready"` to stderr, then blocks indefinitely. Drive: `const c = new AbortController(); const gen = run("ralph", { signal: c.signal }); const nextP = gen.next();` Use `waitForStderr("ready")`, read the child and grandchild PIDs from the markers, then `c.abort()`. Await `nextP` (expected to throw the abort error). Assert: (a) the generator throws an abort error, (b) the child script PID is no longer running (`kill -0 <pid>` → non-zero), and (c) the grandchild PID is also no longer running. This is the programmatic-API counterpart to T-SIG-06 (CLI process-group SIGTERM). *(Spec 9.1, 7.3)* `@flaky-retry(3)`
+- **T-API-10e**: `AbortSignal` escalates to SIGKILL after ~5 seconds when the child ignores SIGTERM. Fixture: `.loopx/ralph/index.sh` installs `trap '' TERM` (ignores SIGTERM), writes its PID to a marker, writes `"ready"` to stderr, then sleeps indefinitely. Drive: `const c = new AbortController(); const gen = run("ralph", { signal: c.signal }); const nextP = gen.next(); await waitForStderr("ready");` Read child PID from marker. Record `start = Date.now()`. Call `c.abort()`. Await `nextP` (expected to throw). Record `end = Date.now()`. Assert: (a) the generator throws an abort error, (b) the child PID is no longer running (SIGKILL took effect — the child cannot trap SIGKILL), (c) `end - start` is within a ~4–7 second tolerance window (grace-period wait before SIGKILL), and (d) the `LOOPX_TMPDIR` cleanup ran before the abort error was thrown (per Spec 7.4 ordering). This is the programmatic-API counterpart to T-SIG-05 (CLI SIGKILL escalation). *(Spec 9.1, 7.3, 7.4)* `@flaky-retry(3)`
+- **T-API-10f**: `generator.return()` terminates the active child process **group** — both child and grandchild die. Same fixture as T-API-10d (child spawns a grandchild, both markered). Drive: `const gen = run("ralph"); const nextP = gen.next(); await waitForStderr("ready");` Read PIDs. Call `await gen.return(undefined);` Assert: (a) the `.return()` resolves cleanly (`{ done: true, value: undefined }`, consumer-driven cancellation is a silent clean completion per Spec 9.1), (b) the child PID is no longer running, and (c) the grandchild PID is also no longer running. Consumer-driven cancellation has the same process-group termination contract as `AbortSignal`. *(Spec 9.1, 7.3)* `@flaky-retry(3)`
+- **T-API-10f-throw**: `generator.throw()` terminates the active child process **group** — both child and grandchild die. `.throw()` counterpart to T-API-10f (`.return()`). SPEC 9.1 requires consumer-driven cancellation to terminate the active child process group regardless of whether the consumer used `.return()`, `.throw()`, or `break` — the process-group termination contract is uniform across the three cancellation forms. T-API-10f covers `.return()`; T-API-10h covers `.throw()` SIGKILL escalation for a *direct* child but not the grandchild / process-group axis. A buggy implementation that forwarded SIGTERM to the direct child only (not the process group) under `.throw()` would leave the grandchild orphaned and pass T-API-10f and T-API-10h while failing this test. Same fixture as T-API-10f / T-API-10d (child spawns a long-lived background grandchild, writes its PID to a marker, writes `"ready"` to stderr, then blocks indefinitely). Drive: `const gen = run("ralph"); const nextP = gen.next(); await waitForStderr("ready");` Read the child and grandchild PIDs from the markers. Call `const settled = await gen.throw(new Error("consumer-err")).catch((e) => ({ rejected: e }));` Assert: (a) the `.throw()` reaches a settled state — either `settled` resolves to `{ done: true }` (silent completion) or settles via rejection (with either the consumer-supplied error or a conforming cancellation error); SPEC 9.1 normatively requires the active child process group to be terminated and no further iterations to start under `.throw()`, but does **not** pin down whether the consumer-supplied error is swallowed vs. surfaced — this test accepts either conforming settlement shape, matching T-API-10h / T-TMP-21's settlement-shape acceptance, (b) the pending `nextP` promise also settles (either resolves or rejects) and does not block indefinitely, (c) the child PID is no longer running (`kill -0 <pid>` → non-zero), and (d) the grandchild PID is also no longer running. This is the active-child process-group counterpart to T-API-10h's SIGKILL-escalation `.throw()` coverage and the `.throw()` counterpart to T-API-10f's `.return()` process-group coverage. *(Spec 9.1, 7.3)* `@flaky-retry(3)`
+- **T-API-10g**: `generator.return()` escalates to SIGKILL after ~5 seconds when the child ignores SIGTERM. Same SIGTERM-ignoring fixture as T-API-10e. Drive: `const gen = run("ralph"); const nextP = gen.next(); await waitForStderr("ready");` Read PID. Record `start`. `await gen.return(undefined);` Record `end`. Assert: (a) the `.return()` resolves cleanly (silent completion), (b) the child PID is no longer running (SIGKILL took effect), (c) `end - start` is within ~4–7s, (d) tmpdir cleanup ran. *(Spec 9.1, 7.3, 7.4)* `@flaky-retry(3)`
+- **T-API-10h**: `generator.throw()` escalates to SIGKILL after ~5 seconds when the child ignores SIGTERM, **and `LOOPX_TMPDIR` cleanup runs before generator settlement**. Same SIGTERM-ignoring fixture as T-API-10g, extended to **observe `LOOPX_TMPDIR` into a marker file external to the tmpdir** (so the marker survives cleanup for the post-settlement read): `.loopx/ralph/index.sh` installs `trap '' TERM` (ignores SIGTERM), reads `OBSERVED_TMPDIR_MARKER` from its environment, writes `$LOOPX_TMPDIR` to that path with `printf '%s' "$LOOPX_TMPDIR" > "$OBSERVED_TMPDIR_MARKER"`, writes its PID to a separate marker, writes `"ready"` to stderr, then sleeps indefinitely. Drive: pass the external observation marker via `RunOptions.env` (`{ env: { OBSERVED_TMPDIR_MARKER: "<abs-path-outside-any-tmpdir>" } }`). `const gen = run("ralph", { env: { OBSERVED_TMPDIR_MARKER } }); const nextP = gen.next(); await waitForStderr("ready");` Read PID and the observed `LOOPX_TMPDIR` path from the markers. Record `start`. Call `const settled = await gen.throw(new Error("consumer-err")).catch((e) => ({ rejected: e }));` Record `end`. Assert: (a) the `.throw()` reaches a settled state (either resolves to `{ done: true }` or rejects — the generator must not hang), (b) the child PID is no longer running (SIGKILL took effect — the child cannot trap SIGKILL), (c) `end - start` is within a ~4–7 second tolerance window (grace-period wait before SIGKILL), and (d) **the observed `LOOPX_TMPDIR` path no longer exists on disk** after `.throw()` settles — cleanup ran before the generator settled, per SPEC 7.4 "Consumer-driven cancellation under `run()` ... `.return()` / `.throw()` after first `next()` — after terminating any active child per section 9.1, before the generator settles". This test pins down that the SIGKILL-escalation path under `.throw()` does **not** skip cleanup, closing the gap between T-TMP-21 (`.throw()` cleanup without SIGKILL escalation — child terminates promptly under SIGTERM) and T-API-10g (`.return()` SIGKILL escalation with cleanup). A buggy implementation that wired tmpdir cleanup into the SIGTERM-prompt-exit path of `.throw()` (passing T-TMP-21) but skipped cleanup when the child required SIGKILL escalation would pass T-API-10g (which covers the `.return()` SIGKILL path) and fail (d) here. **Note:** SPEC 9.1 requires process-group termination with grace-period + SIGKILL escalation for consumer-driven cancellation during active-child execution, but does not pin down whether the consumer-supplied error is swallowed vs. surfaced on the `.throw()` settlement. This test therefore asserts only the process-group-termination + escalation-timing + cleanup-ordering contract that SPEC normatively requires; the consumer-error-propagation outcome is intentionally left unspecified. *(Spec 9.1, 7.3, 7.4)* `@flaky-retry(3)`
+- **T-API-10d-promise**: `AbortSignal` on `runPromise()` terminates the active child process **group** — both child and grandchild die. `runPromise()` accepts the same `RunOptions.signal` option as `run()` per SPEC 9.2 / 9.5, so the process-group-termination contract from SPEC 9.1 / 7.3 applies symmetrically. T-API-10d covers `run()`; this test pins down `runPromise()`. Fixture: `.loopx/ralph/index.sh` spawns a long-lived background grandchild (e.g., `sleep 3600 &`), writes the grandchild PID to a marker, writes `"ready"` to stderr, then blocks indefinitely. Drive: `const c = new AbortController(); const promise = runPromise("ralph", { signal: c.signal });` In parallel, `await waitForStderr("ready")` (using the driver's child-process stderr stream), read the child and grandchild PIDs from the markers, then `c.abort()`. `await expect(promise).rejects.toThrow(<abort error>)`. Assert: (a) the promise rejects with an abort error, (b) the child script PID is no longer running (`kill -0 <pid>` → non-zero), and (c) the grandchild PID is also no longer running. `runPromise()` counterpart to T-API-10d. *(Spec 9.2, 9.1, 9.5, 7.3)* `@flaky-retry(3)`
+- **T-API-10e-promise**: `AbortSignal` on `runPromise()` escalates to SIGKILL after ~5 seconds when the child ignores SIGTERM. Same SIGTERM-ignoring fixture as T-API-10e. Drive: `const c = new AbortController(); const promise = runPromise("ralph", { signal: c.signal }); await waitForStderr("ready");` Read child PID from marker. Record `start = Date.now()`. Call `c.abort()`. `await expect(promise).rejects.toThrow(<abort error>)`. Record `end = Date.now()`. Assert: (a) the promise rejects with an abort error, (b) the child PID is no longer running (SIGKILL took effect — the child cannot trap SIGKILL), (c) `end - start` is within a ~4–7 second tolerance window (grace-period wait before SIGKILL), and (d) the `LOOPX_TMPDIR` cleanup ran before the promise rejection was surfaced (per SPEC 7.4 / 9.3 ordering). `runPromise()` counterpart to T-API-10e — closes SPEC 9.1 / 7.3 SIGKILL-escalation parity on the promise surface. *(Spec 9.2, 9.1, 9.5, 7.3, 7.4, 9.3)* `@flaky-retry(3)`
 
 #### `runPromise()`
 
@@ -1210,7 +2207,7 @@ All env file parsing tests below use `writeEnvFileRaw` to write exact file conte
 - **T-API-48**: `runPromise("ralph:index", { maxIterations: 1 })` is equivalent to `runPromise("ralph", { maxIterations: 1 })` — both resolve with identical Output arrays. This is the `runPromise()` counterpart to T-API-37 (`run()` equivalence test). *(Spec 9.2, 4.1)*
 - **T-API-48a**: `runPromise("check-ready")` where `.loopx/ralph/check-ready.sh` exists but no `.loopx/check-ready/` workflow → rejects. Assert that `ralph:check-ready` was NOT executed (no marker file written). This is the `runPromise()` counterpart to T-API-35e. *(Spec 9.2, 2.2, 4.1)*
 - **T-API-47a**: `runPromise("ralph:check", { maxIterations: 1 })` where `.loopx/ralph/` exists with `check.sh` but no `index` script → resolves with an array containing the Output from `check.sh`. This proves `runPromise()` can target explicit scripts in workflows without an `index` entry point, complementing `run()` coverage (T-API-36a). *(Spec 9.2, 4.1, 2.1)*
-- **T-API-47b**: `runPromise("ralph", { cwd: projectA, maxIterations: 1 })` — `RunOptions.cwd` sets `LOOPX_PROJECT_ROOT` from `cwd` but the script still executes with the workflow directory as cwd. Create a workflow in project A. Script writes both `process.cwd()` and `process.env.LOOPX_PROJECT_ROOT` to a marker file. Assert: (a) cwd equals the workflow directory path (`.loopx/ralph/`), not `projectA`, and (b) `LOOPX_PROJECT_ROOT` equals `projectA`. This is the `runPromise()` counterpart to T-API-07a. *(Spec 9.2, 9.5, 6.1)*
+- **T-API-47b**: `runPromise("ralph", { cwd: projectA, maxIterations: 1 })` — `RunOptions.cwd` sets both `LOOPX_PROJECT_ROOT` and the script execution cwd. Create a workflow in project A. Script writes `process.cwd()` (via `observe-cwd-ts`), `process.env.LOOPX_PROJECT_ROOT` (via `observe-env`), and `process.env.LOOPX_WORKFLOW_DIR` (via `observe-env`) to marker files. Assert: (a) cwd has the same directory identity as `projectA` (not `.loopx/ralph/`), (b) `LOOPX_PROJECT_ROOT` equals the provided `projectA` string, and (c) `LOOPX_WORKFLOW_DIR` equals `projectA/.loopx/ralph/`. This is the `runPromise()` counterpart to T-API-07a and pins down Spec 9.5's unified cwd/project-root semantics on the promise surface. *(Spec 9.2, 9.5, 6.1)*
 
 #### `runPromise()` with Invalid `target`
 
@@ -1225,8 +2222,8 @@ All env file parsing tests below use `writeEnvFileRaw` to write exact file conte
 - **T-API-43**: `runPromise("-bad:index")` rejects (workflow name violates name restrictions). Fixture contains a valid `.loopx/ralph/index.sh`. Assert the rejection error references the name restriction violation. *(Spec 9.2, 4.1)*
 - **T-API-44**: `runPromise("ralph:-bad")` rejects (script name violates name restrictions). Fixture contains a valid `.loopx/ralph/index.sh`. Assert the rejection error references the name restriction violation. *(Spec 9.2, 4.1)*
 - **T-API-44a**: `runPromise("bad.name")` rejects (bare target where the workflow name violates name restrictions). Fixture contains a valid `.loopx/ralph/index.sh`. Assert the rejection error references the name restriction violation. This is the bare-name counterpart to T-API-43 (qualified target with invalid workflow name). *(Spec 9.2, 4.1)*
-- **T-API-44b**: Invalid target format is rejected after discovery and global validation in `runPromise()`, mirroring CLI T-CLI-114a and `run()` generator T-API-35c. Create `.loopx/broken/check.sh` and `.loopx/broken/check.ts` (name collision) alongside `.loopx/valid/index.sh`. Call `runPromise(":script")`. Assert the promise rejects with an error that mentions the name collision in `broken` — proving discovery and global validation ran before the malformed target string was rejected. Per Spec 4.1/9.2, invalid targets in `runPromise()` are rejected "at the same point as a missing workflow (after discovery)." *(Spec 9.2, 4.1, 5.4)*
-- **T-API-44c**: Invalid target with a name-restriction violation is rejected after discovery and global validation in `runPromise()`, mirroring CLI T-CLI-118b and `run()` generator T-API-35f. Create `.loopx/broken/check.sh` and `.loopx/broken/check.ts` (name collision) alongside `.loopx/valid/index.sh`. Call `runPromise("bad.name")` (bare target whose workflow-name portion contains `.`, violating the name restriction pattern `[a-zA-Z0-9_][a-zA-Z0-9_-]*`). Assert the promise rejects with an error that mentions the name collision in `broken` — proving discovery and global validation ran before the invalid bare target name was rejected. T-API-44b covers the ordering proof for malformed colon-shape targets (`":script"`) in `runPromise()`; this test covers the same ordering proof for the name-restriction invalid-target category, a distinct validation path under ADR-0003's expanded target validation rules. Per Spec 4.1/9.2, invalid targets in `runPromise()` are rejected "at the same point as a missing workflow (after discovery)." *(Spec 9.2, 4.1, 5.4)*
+- **T-API-44b**: `runPromise(":script")` in a fixture with a sibling name-collision (`.loopx/broken/check.sh` + `.loopx/broken/check.ts` alongside `.loopx/valid/index.sh`) returns a promise that rejects. Do **not** assert which pre-iteration error wins: SPEC 4.1 says the programmatic API surfaces invalid-target errors via promise rejection on the pre-iteration error path, and "relative ordering against other pre-iteration failures is implementation-defined except for the pinned option-error and abort-precedence rules in section 9.3." This test exists to pin down promise rejection on the mixed-failure-fixture surface, not to mirror CLI T-CLI-114a's ordering guarantee (which is CLI-only). *(Spec 9.2, 4.1)*
+- **T-API-44c**: `runPromise("bad.name")` (bare target whose workflow-name portion contains `.`, violating the name restriction pattern `[a-zA-Z0-9_][a-zA-Z0-9_-]*`) in a fixture with a sibling name-collision (`.loopx/broken/check.sh` + `.loopx/broken/check.ts` alongside `.loopx/valid/index.sh`) returns a promise that rejects. Do **not** assert whether the name-restriction error or the sibling-collision discovery error wins — per SPEC 4.1, the programmatic API leaves this ordering implementation-defined outside of the pinned section 9.3 rules. This test exists to pin down promise rejection in a mixed-failure fixture on the `runPromise()` surface, not the ordering that CLI T-CLI-118b pins down for the CLI surface. *(Spec 9.2, 4.1)*
 - **T-API-45**: `runPromise("ralph")` where workflow `ralph` exists but has no `index` script → rejects (missing default entry point). *(Spec 9.2, 4.1)*
 - **T-API-45a**: `runPromise("ralph:index")` where workflow `ralph` exists but has no `index` script → rejects (missing script `index` in workflow `ralph`). The workflow has other scripts (e.g., `check.sh`) but no `index.*`. The explicit `:index` target follows the ordinary missing-script rule rather than the bare default-entry-point rule. T-API-45 covers the bare `runPromise("ralph")` case (missing-default-entry path); T-API-46 covers a generic missing script (`runPromise("ralph:missing")`); this test pins down the explicit `runPromise("ralph:index")` case. This is the `runPromise()` counterpart to T-API-20j2 and T-CLI-109a, ensuring the promise-based surface enforces the same explicit-`:index` missing rule as the CLI and `run()` generator surfaces. *(Spec 9.2, 4.1)*
 - **T-API-46**: `runPromise("ralph:missing")` where workflow `ralph` exists but script `missing` does not → rejects. *(Spec 9.2, 4.1)*
@@ -1273,11 +2270,14 @@ All env file parsing tests below use `writeEnvFileRaw` to write exact file conte
 - **T-API-17**: Invalid goto target causes `run()` generator to throw. *(Spec 9.3)*
 - **T-API-18**: Script stderr is forwarded to the calling process's stderr. *(Spec 9.3)*
 - **T-API-19**: When `run()` throws, previously yielded outputs are preserved. *(Spec 9.3)*
+- **T-API-19a**: `runPromise()` rejects rather than resolving partial outputs when a later iteration fails. SPEC 9.3: "Partial outputs are preserved. When `run()` throws, all previously yielded outputs have already been consumed by the caller. When `runPromise()` rejects, partial outputs are not available (use `run()` if partial results matter)." T-API-19 covers the `run()` half (yielded outputs survive a later throw); this test pins down the `runPromise()` half — that an early successful iteration's output is **not** delivered when a later iteration fails. Without this test, an implementation that erroneously resolved the promise with `[firstOutput]` (instead of rejecting) when the second iteration failed could pass the existing T-API-16 (non-zero exit causes `runPromise()` to reject) and T-API-19 (`run()` partial preservation) suite while violating SPEC 9.3's runPromise-side contract. Set up two scripts: `.loopx/start/index.sh` outputs `{"goto":"finish:index","result":"first-iteration-marker"}` and writes a side-effect marker file (e.g., `touch $LOOPX_TMPDIR/start-ran`) to prove it executed; `.loopx/finish/index.sh` exits non-zero (e.g., `exit 1`). Drive: `await expect(runPromise("start", { maxIterations: 5 })).rejects.toThrow();` (or use `await runPromise(...)` inside a try/catch that captures the thrown value). Assert: (a) the promise **rejects** (does not resolve), (b) the resolved value is **not** `[{ result: "first-iteration-marker", goto: "finish:index" }]` — i.e., the rejection path was taken, not a partial-result resolution; observe this by ensuring the catch block ran and the resolved value (if any was somehow produced) is undefined or the test assertion `.rejects` succeeded, (c) the rejection reason references the script-failure cause (the second script's non-zero exit), not a "first-output-only resolution" outcome, and (d) the `start-ran` marker file exists, proving the first iteration did execute and produce its output before the second iteration failed (otherwise the test would not distinguish "promise rejected because nothing ran" from "promise rejected despite a partial output existing"). A buggy implementation that accumulated outputs into the resolution array and resolved with `[firstOutput]` on later failure (instead of rejecting) would fail (a). An implementation that rejected but lost the proof that the first iteration ran would fail (d) — the test would not be exercising the partial-output rejection path. *(Spec 9.2, 9.3)*
 - **T-API-20a**: `run("nonexistent")` → generator throws on first `next()`. *(Spec 9.1, 9.3)*
 - **T-API-20b**: `runPromise("nonexistent")` → rejects. *(Spec 9.3)*
 - **T-API-20c**: `run("ralph")` with name collision in `.loopx/` → generator throws on first `next()`. *(Spec 9.1, 9.3)*
 - **T-API-20d**: `run("ralph", { envFile: "nonexistent.env" })` → generator throws on first `next()`. *(Spec 9.1, 9.3, 9.5)*
+- **T-API-20d2**: `run("ralph", { envFile: "unreadable.env" })` where `unreadable.env` exists but is unreadable (e.g., mode 000) → generator throws on first `next()`. Unreadable-file counterpart to T-API-20d (missing file), exercising the programmatic API's normal-path env-file readability validation — T-API-08p covers the same failure mode under `maxIterations: 0`, but the normal (non-zero-iteration) `run()` path is a separate code path per SPEC 9.1 pre-iteration ordering and ADR-0003's `envFile` handling on ordinary execution. **Conditional on `process.getuid() !== 0`.** *(Spec 9.1, 9.3, 9.5, 4.2, 8.2)*
 - **T-API-20e**: `runPromise("ralph", { envFile: "nonexistent.env" })` → rejects. *(Spec 9.3, 9.5)*
+- **T-API-20e2**: `runPromise("ralph", { envFile: "unreadable.env" })` where `unreadable.env` exists but is unreadable (e.g., mode 000) → rejects. Unreadable-file counterpart to T-API-20e (missing file) and `runPromise()` twin of T-API-20d2, providing generator/promise symmetry for the unreadable local env file case on the normal-execution path. T-API-08p2 covers the same failure mode under `maxIterations: 0`. **Conditional on `process.getuid() !== 0`.** *(Spec 9.2, 9.3, 9.5, 4.2, 8.2)*
 - **T-API-20f**: `run("ralph", { cwd: dirWithoutLoopx })` → generator throws on first `next()`. *(Spec 9.1, 9.3)*
 - **T-API-20g**: `runPromise("ralph", { cwd: dirWithoutLoopx })` → rejects. *(Spec 9.3)*
 - **T-API-20j**: `run("ralph")` where workflow `ralph` exists but has no `index` script → generator throws on first `next()` (missing default entry point). *(Spec 9.1, 4.1)*
@@ -1302,6 +2302,14 @@ All env file parsing tests below use `writeEnvFileRaw` to write exact file conte
 - **T-API-21b**: Relative envFile path resolved against `process.cwd()` when no `cwd` option. *(Spec 9.5)*
 - **T-API-21c**: Env file parse warnings forwarded to stderr via programmatic API. *(Spec 8.1, 9.3)*
 - **T-API-21d**: Global env file parse warnings forwarded to stderr. *(Spec 8.1, 9.3)*
+- **T-API-21e**: Absolute `envFile` path used unchanged on the **`runPromise()`** surface. SPEC 9.5: "Relative `envFile` paths are resolved against the resolved project root (which equals the child's cwd) when `cwd` is supplied, otherwise against `process.cwd()` at call time." By implication (and consistent with SPEC 9.5's absolute-`cwd` "used unchanged" rule), an absolute `envFile` path is used unchanged — no relative-path resolution applies. Create a project at `/tmp/test-project/` with `.loopx/ralph/index.sh` (emits `stop: true`) and an env file at an absolute path **outside** the project (e.g., `/tmp/outside-envs/absolute.env`) containing `MARKER_VAR=absolute-path-win`. The script observes `MARKER_VAR` into an external marker file via `observe-env`. Call `runPromise("ralph", { cwd: "/tmp/test-project", envFile: "/tmp/outside-envs/absolute.env", maxIterations: 1 })`. Assert: (a) the promise resolves (no rejection — the absolute path is used unchanged, even though it sits outside the supplied `cwd`), and (b) the marker records `MARKER_VAR = "absolute-path-win"`, proving the absolute `envFile` was loaded from its supplied path and not re-rooted under `cwd`. An implementation that incorrectly joined `cwd` + `envFile` as if `envFile` were relative would look for `/tmp/test-project/tmp/outside-envs/absolute.env`, which does not exist, and would reject — so a rejection or a missing `MARKER_VAR` fails this test. T-API-21e2 covers the `run()` generator surface counterpart. *(Spec 9.5)*
+- **T-API-21e2**: Absolute `envFile` path used unchanged on the **`run()`** generator surface. Generator-surface counterpart to T-API-21e (`runPromise()`). SPEC 9.5's absolute-path-used-unchanged rule applies symmetrically across `run()` and `runPromise()`. The two surfaces have **different snapshot timing** for the option-snapshot pass and pre-iteration env-file loading (lazy at first-`next()` under `run()` per SPEC 9.1; eager at the call site under `runPromise()` per SPEC 9.2) — a buggy implementation that handled the absolute-path branch correctly on the eager-snapshot `runPromise()` path but mis-applied a relative-path resolution on the lazy-snapshot `run()` path (e.g., by joining `cwd` + `envFile` inside the deferred pre-iteration block on `run()`) would pass T-API-21e and fail this test. **Setup.** Identical to T-API-21e: create a project at `/tmp/test-project/` with `.loopx/ralph/index.sh` (observes `MARKER_VAR` into an external marker via `observe-env` and emits `{"stop":true}`), and place an env file at `/tmp/outside-envs/absolute.env` containing `MARKER_VAR=absolute-path-win`. **Drive.** `const gen = run("ralph", { cwd: "/tmp/test-project", envFile: "/tmp/outside-envs/absolute.env", maxIterations: 1 }); for await (const _ of gen) {}` (or equivalent generator drive). **Assert.** (a) the generator settles cleanly (no error), and (b) the marker records `MARKER_VAR = "absolute-path-win"`, proving the absolute `envFile` was loaded from its supplied path and not re-rooted under `cwd`. An implementation that incorrectly joined `cwd` + `envFile` as if `envFile` were relative on the `run()` path would look for `/tmp/test-project/tmp/outside-envs/absolute.env`, which does not exist, and would surface an env-file-load error on first `next()` — so a generator throw or a missing `MARKER_VAR` fails this test. Together with T-API-21e (`runPromise()`) this closes the absolute-`envFile`-used-unchanged contract on both API surfaces. *(Spec 9.5, 9.1)*
+- **T-API-21f**: Relative `envFile` is resolved at **call time**, not at first `next()`, when no `cwd` option is supplied. SPEC 9.5 pairs with SPEC 9.1 option-snapshot timing: option fields are read synchronously at the call site, and relative path resolution for `envFile` / `cwd` happens once at call time. Under `run()`, pre-iteration work (discovery, env-file *loading*) happens at first `next()`, but the *resolution* of a relative `envFile` path is still pinned to the call-time `process.cwd()`. Because `cwd` also defaults to `process.cwd()` at call time (SPEC 9.5), a fixture that *omits* `cwd` must place the full project under the same directory that `process.cwd()` points to at the `run()` call site — otherwise discovery would look under the wrong `.loopx/` root and the test would fail for a reason unrelated to `envFile` resolution timing. Use **two full projects** so the call-time vs. next-time distinction is an end-to-end observation: `projectA/` with `.loopx/ralph/index.sh` (observes `MARKER_VAR` into an external marker) and `projectA/local.env` containing `MARKER_VAR=from-A`; `projectB/` with the *same* `.loopx/ralph/index.sh` and `projectB/local.env` containing `MARKER_VAR=from-B`. Drive: (1) `process.chdir(projectA);` (2) `const gen = run("ralph", { envFile: "local.env", maxIterations: 1 });` — the relative `envFile` resolves against `process.cwd()` at call time, which is `projectA`, so the snapshot pins `envFile` to `projectA/local.env`; `cwd` also snapshots to `projectA`. (3) `process.chdir(projectB);` — **mutate `process.cwd()` between `run()` returning and first `next()`**. (4) `const { value } = await gen.next();`. Assert: (a) the script that ran was `projectA`'s script (the pre-iteration work including `.loopx/` discovery ran in `projectA`, not `projectB`, even though `process.cwd()` changed to `projectB` before first `next()`), and (b) the marker records `MARKER_VAR = "from-A"`, proving the relative `envFile` was resolved to `projectA/local.env` at call time. An implementation that deferred relative-path resolution to first `next()` would instead load `projectB/local.env` and write `"from-B"` to the marker, and would also run `projectB`'s `.loopx/ralph/index.sh`. Together, these two assertions test both the default-`cwd` call-time capture (SPEC 9.5: "Defaults to `process.cwd()` at the time `run()` or `runPromise()` is called") and the relative-`envFile` call-time resolution under the no-`cwd` branch of SPEC 9.5's envFile resolution rule. For safety across runtimes, perform the run under a driver that fully isolates `process.cwd()` mutations (use `runAPIDriver` with the chdir orchestration inside the driver code). **Test must restore original cwd in a `finally` block** to avoid leaking the chdir to other tests. *(Spec 9.5, 9.1)*
+- **T-API-21g**: Explicit relative `cwd` is resolved at **call time**, even if `process.chdir()` changes before first `next()`. SPEC 9.5: "A relative `cwd` is resolved via `path.resolve(process.cwd(), options.cwd)` once at call time." Under `run()`, the resolution happens synchronously at the `run()` call site even though pre-iteration work is deferred to first `next()`. Create two projects: `/tmp/projects-at-call/my-project/` with `.loopx/ralph/index.sh` (emits a marker identifying the project and `stop: true`), and `/tmp/projects-at-next/my-project/` with `.loopx/ralph/index.sh` (emits a distinct marker). Drive under a driver (e.g., `runAPIDriver`): (1) `process.chdir("/tmp/projects-at-call");` (2) `const gen = run("ralph", { cwd: "./my-project", maxIterations: 1 });` — the relative `cwd` `./my-project` resolves against `/tmp/projects-at-call` via `path.resolve("/tmp/projects-at-call", "./my-project")` = `/tmp/projects-at-call/my-project/`. (3) `process.chdir("/tmp/projects-at-next");` — change cwd between `run()` returning and first `next()`. (4) `const { value } = await gen.next();`. Assert the marker recorded is the one from `/tmp/projects-at-call/my-project/` — proving the relative `cwd` was resolved at call time, not re-resolved against the changed `process.cwd()` at first `next()`. An implementation that deferred relative-`cwd` resolution would instead spawn `.loopx/ralph/index.sh` from `/tmp/projects-at-next/my-project/`, writing a different marker. **Test must restore original cwd in a `finally` block.** This test pins down the "`path.resolve(process.cwd(), options.cwd)` once at call time" clause of SPEC 9.5 on the relative-`cwd` surface, closing the call-time / next-time timing gap in the existing T-SYM-03 / T-SYM-04 coverage. *(Spec 9.5, 9.1)*
+- **T-API-21h**: `runPromise()` counterpart to T-API-21f — relative `envFile` is resolved at **call time**, not later, when no `cwd` option is supplied; `process.chdir()` between the synchronous `runPromise()` return and `await` does not redirect resolution. SPEC 9.2 says `runPromise()` snapshots inherited `process.env` eagerly at the call site, and SPEC 9.5 says relative `envFile` paths "are resolved against ... `process.cwd()` at call time" when `cwd` is not supplied — so under `runPromise()` the call-time pinning is even stricter than under `run()` (no first-`next()` deferral). T-API-21f covers the `run()` generator surface; `runPromise()` has no equivalent direct test. A buggy `runPromise()` implementation that deferred relative-path resolution to a microtask boundary inside the returned promise — for example, by wrapping the body in `await Promise.resolve().then(...)` and reading `process.cwd()` inside the `.then` — would resolve `envFile` against the post-`chdir` value. Use **two full projects** so the call-time vs. async-resolution distinction is end-to-end observable, mirroring T-API-21f's fixture: `projectA/` with `.loopx/ralph/index.sh` (observes `MARKER_VAR` into an external marker via `observe-env` and emits `stop:true`) and `projectA/local.env` containing `MARKER_VAR=from-A`; `projectB/` with the *same* `.loopx/ralph/index.sh` and `projectB/local.env` containing `MARKER_VAR=from-B`. Drive under a driver that fully isolates `process.cwd()` mutations (e.g., `runAPIDriver`): (1) `process.chdir(projectA);` (2) `const promise = runPromise("ralph", { envFile: "local.env", maxIterations: 1 });` — the call-site captures `process.cwd()` as the default for `cwd`, captures the inherited env eagerly per SPEC 9.2, and resolves `envFile` against `process.cwd()` (= `projectA`) per SPEC 9.5, pinning the env file to `projectA/local.env`. (3) `process.chdir(projectB);` — **mutate `process.cwd()` between the synchronous `runPromise()` return and the `await`**. (4) `const outputs = await promise;`. Assert: (a) the script that ran was `projectA`'s script (the implicit project root captured at call time was `projectA`, so `.loopx/` discovery happened under `projectA`, not `projectB`, even though `process.cwd()` changed before `await`), and (b) the marker records `MARKER_VAR = "from-A"`, proving the relative `envFile` was resolved to `projectA/local.env` at call time. An implementation that deferred relative-path resolution would instead load `projectB/local.env` and write `"from-B"` to the marker, and would also run `projectB`'s `.loopx/ralph/index.sh`. Together with T-API-21f, this closes the call-time-resolution-of-relative-envFile-under-no-`cwd` gap on both API surfaces. **Test must restore original cwd in a `finally` block** to avoid leaking the chdir to other tests. *(Spec 9.5, 9.2)*
+- **T-API-21i**: `runPromise()` counterpart to T-API-21g — explicit relative `cwd` is resolved at **call time**; `process.chdir()` between the synchronous `runPromise()` return and `await` does not redirect resolution. SPEC 9.5: "A relative `cwd` is resolved via `path.resolve(process.cwd(), options.cwd)` once at call time"; SPEC 9.2 makes `runPromise()`'s pre-iteration snapshot eager at the call site. T-API-21g covers the `run()` generator surface; `runPromise()` has no equivalent direct test. A buggy `runPromise()` implementation that deferred relative-`cwd` resolution into the returned promise's body — even though SPEC 9.5 says resolution happens "once at call time" — would resolve against the post-`chdir` value. Create two projects: `/tmp/projects-at-call/my-project/` with `.loopx/ralph/index.sh` (emits a marker identifying the project and `stop: true`), and `/tmp/projects-at-next/my-project/` with `.loopx/ralph/index.sh` (emits a distinct marker). Drive under a driver (e.g., `runAPIDriver`): (1) `process.chdir("/tmp/projects-at-call");` (2) `const promise = runPromise("ralph", { cwd: "./my-project", maxIterations: 1 });` — the relative `cwd` `./my-project` resolves against `/tmp/projects-at-call` via `path.resolve("/tmp/projects-at-call", "./my-project")` = `/tmp/projects-at-call/my-project/` synchronously at the call site. (3) `process.chdir("/tmp/projects-at-next");` — change cwd between `runPromise()` returning and the `await`. (4) `const outputs = await promise;`. Assert the marker recorded is the one from `/tmp/projects-at-call/my-project/` — proving the relative `cwd` was resolved at call time, not re-resolved against the changed `process.cwd()` at promise-body execution. An implementation that deferred relative-`cwd` resolution would instead spawn `.loopx/ralph/index.sh` from `/tmp/projects-at-next/my-project/`, writing a different marker. **Test must restore original cwd in a `finally` block.** Together with T-API-21g, this closes the call-time / async-body timing gap on both API surfaces for relative `cwd`. *(Spec 9.5, 9.2)*
+- **T-API-21j**: `runPromise()` — relative `envFile` resolved against the resolved (relative) `cwd` is pinned at **call time**, even if `process.chdir()` runs between the synchronous `runPromise()` return and `await`. Combines the relative-`cwd` and relative-`envFile` axes of SPEC 9.5: "Relative `envFile` paths are resolved against the resolved project root (which equals the child's cwd) when `cwd` is supplied" — and "A relative `cwd` is resolved via `path.resolve(process.cwd(), options.cwd)` once at call time." T-API-21h covers the no-`cwd` envFile case (envFile resolves against `process.cwd()` at call time); T-API-21i covers the relative-`cwd` case alone (no envFile). This test covers the **interaction** — relative `cwd` resolves to `projectA/` at call time, and the relative `envFile` then resolves under that resolved project root, also at call time, so a chdir between return and `await` must not affect either resolution. A buggy implementation that handled relative-`cwd` resolution at call time but deferred relative-`envFile` resolution to the promise body (or vice versa) would only fail this combined test. Set up: `/tmp/projects-at-call/my-project/` with `.loopx/ralph/index.sh` (observes `MARKER_VAR` into a marker via `observe-env`, also emits a project-identifier marker so the project axis is observable, and emits `stop: true`) and `/tmp/projects-at-call/my-project/local.env` containing `MARKER_VAR=from-A`; `/tmp/projects-at-next/my-project/` with the *same* `.loopx/ralph/index.sh` and `/tmp/projects-at-next/my-project/local.env` containing `MARKER_VAR=from-B`. Drive under a driver (e.g., `runAPIDriver`): (1) `process.chdir("/tmp/projects-at-call");` (2) `const promise = runPromise("ralph", { cwd: "./my-project", envFile: "local.env", maxIterations: 1 });` — the relative `cwd` `./my-project` resolves to `/tmp/projects-at-call/my-project/`; the relative `envFile` `local.env` then resolves against the resolved project root to `/tmp/projects-at-call/my-project/local.env`, both at call time. (3) `process.chdir("/tmp/projects-at-next");` — mutate cwd between return and `await`. (4) `const outputs = await promise;`. Assert: (a) the project-identifier marker records the `/tmp/projects-at-call/my-project/` script (proving the resolved `cwd` was pinned at call time), and (b) the `MARKER_VAR` marker records `"from-A"` (proving the relative `envFile` was resolved against the call-time-resolved project root, not against `process.cwd()` at any later moment, and not under `/tmp/projects-at-next/my-project/`). An implementation that deferred either resolution to the post-return promise body would resolve against `/tmp/projects-at-next/`, write `"from-B"` to the `MARKER_VAR` marker, and run the wrong project's script — failing assertion (a), assertion (b), or both. **Test must restore original cwd in a `finally` block.** This test closes the combined-axis timing gap that T-API-21h (envFile-only) and T-API-21i (cwd-only) leave open on the `runPromise()` surface. *(Spec 9.5, 9.2)*
+- **T-API-21k**: `run()` — relative `envFile` resolved against the resolved (relative) `cwd` is pinned at **call time**, even if `process.chdir()` runs between the synchronous `run()` return and the first `next()`. Generator-surface counterpart to T-API-21j (`runPromise()`). T-API-21f covers the `run()` no-`cwd` envFile case (envFile resolves against `process.cwd()` at call time), and T-API-21g covers the `run()` relative-`cwd` case alone (no envFile). This test covers the **interaction** on the generator surface — relative `cwd` resolves to `projectA/` at call time, and the relative `envFile` then resolves under that resolved project root, also at call time, so a chdir between `run()` returning and the first `next()` must not affect either resolution. A buggy implementation that handled both axes correctly *separately* on the `run()` surface (passing T-API-21f and T-API-21g) but deferred relative-`envFile` resolution to first `next()` only when `cwd` was also relative — for example, a code path that wired up the joint resolution under a single deferred branch — would pass T-API-21f / T-API-21g and fail this combined test. The `runPromise()` surface has the same gap closed by T-API-21j; the `run()` surface needs its own pin because SPEC 9.1's lazy snapshot timing for `run()` (versus SPEC 9.2's eager snapshot for `runPromise()`) means each surface evaluates the option-snapshot on a different schedule, and the relative-resolution-at-call-site contract must hold under both. Set up: `/tmp/projects-at-call/my-project/` with `.loopx/ralph/index.sh` (observes `MARKER_VAR` into a marker via `observe-env`, emits a project-identifier marker, and emits `stop: true`) and `/tmp/projects-at-call/my-project/local.env` containing `MARKER_VAR=from-A`; `/tmp/projects-at-next/my-project/` with the *same* `.loopx/ralph/index.sh` and `/tmp/projects-at-next/my-project/local.env` containing `MARKER_VAR=from-B`. Drive under a driver (e.g., `runAPIDriver`): (1) `process.chdir("/tmp/projects-at-call");` (2) `const gen = run("ralph", { cwd: "./my-project", envFile: "local.env", maxIterations: 1 });` — the relative `cwd` `./my-project` resolves to `/tmp/projects-at-call/my-project/` synchronously at the call site; the relative `envFile` `local.env` then resolves against the resolved project root to `/tmp/projects-at-call/my-project/local.env`, also at call site. (3) `process.chdir("/tmp/projects-at-next");` — mutate `process.cwd()` between `run()` returning and the first `next()`. (4) `const { value } = await gen.next();` — drain to completion. Assert: (a) the project-identifier marker records the `/tmp/projects-at-call/my-project/` script (proving the resolved `cwd` was pinned at call time, matching T-API-21g's contract on the joint axis), (b) the `MARKER_VAR` marker records `"from-A"` (proving the relative `envFile` was resolved against the call-time-resolved project root, not against `process.cwd()` at first `next()`, and not under `/tmp/projects-at-next/my-project/`), and (c) the generator settles cleanly. An implementation that resolved each axis correctly in isolation but deferred `envFile` resolution to first `next()` only when `cwd` was also relative would resolve against `/tmp/projects-at-next/`, write `"from-B"` to the `MARKER_VAR` marker, and may also run the wrong project's script — failing (a), (b), or both. **Test must restore original cwd in a `finally` block.** Together with T-API-21j (`runPromise()`), this closes the combined-axis call-time-resolution gap on both API surfaces. *(Spec 9.5, 9.1)*
 
 #### `maxIterations` Validation
 
@@ -1311,6 +2319,14 @@ All env file parsing tests below use `writeEnvFileRaw` to write exact file conte
 - **T-API-24**: `runPromise("ralph", { maxIterations: NaN })` → rejects. *(Spec 9.5)*
 - **T-API-24a**: `runPromise("ralph", { maxIterations: -1 })` → rejects. *(Spec 9.5)*
 - **T-API-24b**: `runPromise("ralph", { maxIterations: 1.5 })` → rejects. *(Spec 9.5)*
+- **T-API-24c**: `run("ralph", { maxIterations: Infinity as any })` → generator throws on first `next()` with an invalid-`maxIterations` error. Per SPEC 9.5, `maxIterations` must be a non-negative finite integer; `Infinity` is not finite. T-API-22 covers negative, T-API-23 covers non-integer (1.5), T-API-23a / T-API-24 cover `NaN`; this closes the `Infinity` gap, which some implementations accept as "run forever" accidentally via loose `typeof === "number"` checks that do not call `Number.isFinite`. *(Spec 9.1, 9.5)*
+- **T-API-24d**: `runPromise("ralph", { maxIterations: Infinity as any })` → rejects with an invalid-`maxIterations` error. `runPromise` counterpart to T-API-24c. *(Spec 9.5)*
+- **T-API-24e**: `run("ralph", { maxIterations: null as any })` → generator throws on first `next()`. `null` is not a number and therefore not a valid `maxIterations`. Some shape-validators accept `null` because `typeof null === "object"` or because a permissive "if present, validate" check treats `null` the same as "not provided." SPEC 9.5 requires `maxIterations`, when supplied, to be a non-negative finite integer; `null` is supplied (it is an explicit own property of the options object) and does not satisfy that predicate. *(Spec 9.1, 9.5)*
+- **T-API-24f**: `runPromise("ralph", { maxIterations: null as any })` → rejects. `runPromise` counterpart to T-API-24e. *(Spec 9.5)*
+- **T-API-24g**: `run("ralph", { maxIterations: "1" as any })` → generator throws on first `next()`. Per SPEC 9.5, the `maxIterations` type is `number | undefined`; a string value — even one that parses to a valid non-negative integer — must be rejected by shape validation. Closes the loose-coercion gap that a `Number("1") === 1` coercion would introduce. *(Spec 9.1, 9.5)*
+- **T-API-24h**: `runPromise("ralph", { maxIterations: "1" as any })` → rejects. `runPromise` counterpart to T-API-24g. *(Spec 9.5)*
+- **T-API-24i**: `runPromise()` — `maxIterations` counts loop hops, not just yields, across cross-workflow and intra-workflow goto chains. SPEC 4.2 / 7.1 define `maxIterations` as the number of iterations (each spawn of a script counts as one iteration), and SPEC 2.2 makes `goto` part of the iteration count rather than a free transition. CLI iteration counting across gotos is pinned down by T-LOOP-06 / T-LOOP-07 / T-LOOP-08 and related; the API equivalent is only implicitly covered. This test pins down the explicit API contract. Set up three scripts: `.loopx/ralph/index.sh` (outputs `{"goto":"check","result":"A"}`), `.loopx/ralph/check.sh` (outputs `{"goto":"other:step","result":"B"}`), and `.loopx/other/step.sh` (outputs `{"stop":true,"result":"C"}`). Case 1: `await runPromise("ralph", { maxIterations: 2 })` — the loop should run `index` then `check` and then terminate on the iteration budget, yielding exactly two outputs with `result` values `["A", "B"]`. The third goto target (`other:step`) is not entered because `maxIterations: 2` exhausts the budget after the second iteration. Case 2: `await runPromise("ralph", { maxIterations: 3 })` — the loop runs all three, yielding exactly three outputs with `result` values `["A", "B", "C"]`. Asserting the output counts and the specific `result` sequence proves (a) `maxIterations` counts each spawn as one iteration regardless of whether it is reached via goto or loop reset, (b) intra-workflow goto (`index` → `check`) consumes one iteration, and (c) cross-workflow goto (`check` → `other:step`) consumes one iteration. A buggy implementation that counted only cross-workflow transitions, or that allowed a goto to exceed the limit "for free", would produce different output counts and fail this test. *(Spec 9.2, 9.5, 7.1, 2.2)*
+- **T-API-24j**: `run()` — `maxIterations` counts loop hops across goto chains. Generator-surface counterpart to T-API-24i. Same three-script fixture. Case 1: `const gen = run("ralph", { maxIterations: 2 })` then iterate to exhaustion via `for await`; assert exactly two yielded outputs with `result` values `["A", "B"]`. Case 2: `maxIterations: 3`; assert exactly three yielded outputs `["A", "B", "C"]`. Together with T-API-24i (`runPromise`), this closes the API `maxIterations`-counts-goto-hops gap across both surfaces. *(Spec 9.1, 9.5, 7.1, 2.2)*
 
 #### `runPromise()` with AbortSignal
 
@@ -1318,12 +2334,353 @@ All env file parsing tests below use `writeEnvFileRaw` to write exact file conte
 - **T-API-25a**: Pre-aborted signal → rejects immediately, no child spawned. *(Spec 9.5)*
 - **T-API-25b**: Abort between iterations → rejects. *(Spec 9.5, 9.2)*
 
+#### `RunOptions.env` (Programmatic Env Injection)
+
+Spec 9.5 adds an `env?: Record<string, string>` field to `RunOptions`. These tests cover shape validation, snapshot semantics, precedence, and boundary cases. All fixtures use `observe-env` to distinguish set-vs-absent.
+
+##### Basic Injection
+
+- **T-API-50**: `RunOptions.env` injects a variable into every spawned script. `runPromise("ralph", { env: { MYVAR: "hello" }, maxIterations: 1 })`. Script observes `MYVAR`. Assert marker shows `{ present: true, value: "hello" }`. *(Spec 9.5, 8.3)*
+- **T-API-50a**: `RunOptions.env` applies to every script across iterations. Two iterations; both observe `MYVAR`. Assert both markers show `"hello"`. *(Spec 9.5, 8.3)*
+- **T-API-50b**: `RunOptions.env` applies across intra-workflow goto. `ralph:index` gotos `ralph:check`. Both observe `MYVAR`. Assert both show `"hello"`. *(Spec 9.5, 8.3)*
+- **T-API-50c**: `RunOptions.env` applies across cross-workflow goto. `alpha:index` gotos `beta:step`. Both observe `MYVAR`. Assert both show `"hello"`. *(Spec 9.5, 8.3)*
+- **T-API-50d**: `RunOptions.env` applies on loop reset. Multi-iteration loop where reset returns to the starting target. Observe `MYVAR` on every iteration. Assert every observation shows `"hello"`. *(Spec 9.5, 8.3)*
+- **T-API-50f**: Concurrent `runPromise()` calls receive isolated `RunOptions.env` values. Pins down ADR-0004's core motivation that programmatic per-run env values reach scripts without racy global `process.env` mutation. Existing T-API-50–50d / T-API-51e–51f / T-API-52–52e2 cover injection / precedence / snapshot semantics on individual runs, but none directly assert that **two overlapping concurrent runs** with different `RunOptions.env` values do not cross-contaminate. A buggy implementation that internally mutated `process.env` to apply per-run values, even temporarily across the spawn step, would observably leak across concurrent runs and pass every existing test (which uses one run at a time). Set up two distinct workflows in the same project (`alpha` and `beta`) — `.loopx/alpha/index.sh` observes `MYVAR` via `observe-env` into a marker at `$LOOPX_TMPDIR/../alpha-marker-<unique>` (or another caller-supplied absolute path supplied through a second env var), then waits for a caller-supplied "release" file to appear, then emits `stop: true`; `.loopx/beta/index.sh` does the same with its own marker / release pair. The wait-for-release mechanism guarantees the two scripts overlap on the `RunOptions.env` snapshot / spawn boundary — when one script blocks waiting for its release file, the other script is already past `runPromise()`-call but has not yet completed its iteration. Drive: `const releaseAlpha = path.join(tmp, "release-alpha"); const releaseBeta = path.join(tmp, "release-beta"); const pAlpha = runPromise("alpha", { env: { MYVAR: "alpha-value", ALPHA_MARKER: alphaMarkerPath, ALPHA_RELEASE: releaseAlpha }, maxIterations: 1 }); const pBeta = runPromise("beta", { env: { MYVAR: "beta-value", BETA_MARKER: betaMarkerPath, BETA_RELEASE: releaseBeta }, maxIterations: 1 });` Wait for both `alphaMarkerPath` and `betaMarkerPath` to exist on disk (each script writes its marker before blocking). At this point both scripts are blocked waiting for their release files, so both `runPromise()` calls have completed their `RunOptions.env` snapshot and spawned their scripts with their respective env values — the runs genuinely overlap. Touch both release files to unblock both scripts. Await `pAlpha` and `pBeta`. Read both markers. Assert: (a) `alphaMarkerPath` records `MYVAR === "alpha-value"` (alpha's run saw only its own env value), (b) `betaMarkerPath` records `MYVAR === "beta-value"` (beta's run saw only its own env value), (c) neither marker contains the other run's value (no cross-contamination), (d) both promises resolve (no rejection). A buggy implementation that mutated `process.env.MYVAR` to apply per-run values would surface as one or both markers observing the wrong value (e.g., both markers showing `"beta-value"` if beta's mutation overwrote alpha's before alpha spawned). T-API-50–50e cover the single-run injection axis; this test pins down the concurrent-isolation axis directly on the `runPromise()` surface; T-API-50g extends the same contract to the `run()` generator surface. *(Spec 9.5, 9.2, 8.3)*
+- **T-API-50g**: Concurrent `run()` generator calls receive isolated `RunOptions.env` values. `run()`-surface counterpart to T-API-50f, pinning down the same concurrent-isolation contract on the generator surface. ADR-0004's motivation for `RunOptions.env` is to avoid racy global `process.env` mutation for **both** API surfaces; a buggy implementation that mutated `process.env` to apply per-run values could leak across concurrent runs on either surface, and the two surfaces have different snapshot timing for inherited `process.env` (lazy under `run()` per SPEC 9.1; eager under `runPromise()` per SPEC 9.2), so an implementation that wired `RunOptions.env` correctly on the eager `runPromise()` path while losing isolation on the lazy `run()` path — for example, by re-reading shared mutable state at first `next()` rather than from a captured snapshot — would pass T-API-50f and fail this test. **Same fixture as T-API-50f**: two distinct workflows `alpha` and `beta` in the same project, each with `index.sh` that observes `MYVAR` via `observe-env` into a caller-supplied marker path, waits for a caller-supplied release file to appear, then emits `stop: true`. **Drive on the generator surface**: `const releaseAlpha = path.join(tmp, "release-alpha"); const releaseBeta = path.join(tmp, "release-beta"); const ga = run("alpha", { env: { MYVAR: "alpha-value", ALPHA_MARKER: alphaMarkerPath, ALPHA_RELEASE: releaseAlpha }, maxIterations: 1 }); const gb = run("beta", { env: { MYVAR: "beta-value", BETA_MARKER: betaMarkerPath, BETA_RELEASE: releaseBeta }, maxIterations: 1 }); const aNextP = ga.next(); const bNextP = gb.next();` — starting both `next()` calls **without awaiting** forces both generators past their `RunOptions.env` snapshots and into their first child spawns concurrently while the harness retains control. Awaiting `Promise.all([ga.next(), gb.next()])` here would deadlock, because the fixture scripts block at the release-file boundary before yielding their first output, so neither `next()` promise can resolve until the release files are touched. With the un-awaited promises in hand, wait for both `alphaMarkerPath` and `betaMarkerPath` to exist on disk (each script writes its marker before blocking) — at that point both generators are blocked at the release-file boundary, so both `run()` calls have completed their `RunOptions.env` snapshot and spawned their scripts with their respective env values, and the runs genuinely overlap. Touch both release files to unblock both scripts, then `const [aFirst, bFirst] = await Promise.all([aNextP, bNextP]);` to await both first yields. Drain both generators to settlement: `for await (const _ of ga) {} for await (const _ of gb) {}` (or equivalent — both should settle cleanly with the per-iteration limit reached). Read both markers. Assert: (a) `alphaMarkerPath` records `MYVAR === "alpha-value"` (alpha's generator saw only its own env value), (b) `betaMarkerPath` records `MYVAR === "beta-value"` (beta's generator saw only its own env value), (c) neither marker contains the other run's value (no cross-contamination), (d) both generators settle cleanly (no errors thrown). Together with T-API-50f (`runPromise()` surface), this closes the concurrent-`RunOptions.env` isolation contract across both API surfaces, completing the surface symmetry the ADR motivates. *(Spec 9.5, 9.1, 8.3)*
+- **T-API-50e**: `RunOptions.env` accepts an **empty-string value** and the variable reaches the spawned script as the empty string. Per SPEC 9.5 "Shape ... whose own enumerable string-keyed entries all have string values" — an empty string IS a string and is a conforming value. SPEC 8.3 / 9.5 do not single empty values out for special handling, so empty-string entries must propagate through the merge tier and reach the child like any other string-valued entry. The env-file tier has comparable coverage (e.g., empty values from `KEY=` / `KEY=""` in env files), but `RunOptions.env` does not currently have a positive empty-string-value test. A buggy implementation that filtered out falsy entries (`if (value)` rather than `if (typeof value === "string")`) would silently drop the empty value and pass T-API-50 / T-API-50a–d (which all use a non-empty value). Set up `.loopx/ralph/index.ts` containing a TS script that observes `process.env.EMPTY` via the `observe-env` fixture (which JSON-encodes the observed value, so an empty string is distinguishable from `undefined`). Call `runPromise("ralph", { env: { EMPTY: "" }, maxIterations: 1 })`. Assert: (a) the promise resolves (no rejection — empty string is a valid value, not a shape error), (b) the marker file records `process.env.EMPTY === ""` (present, value is the empty string — **not** absent / `undefined`). A buggy implementation that dropped empty-string entries would produce a marker showing `undefined` / absent and fail (b). *(Spec 8.3, 9.5)*
+
+##### Precedence
+
+- **T-API-51a**: `RunOptions.env` is overridden by protocol variables. `runPromise("ralph", { env: { LOOPX_WORKFLOW: "fake", LOOPX_PROJECT_ROOT: "/tmp/fake", LOOPX_WORKFLOW_DIR: "/tmp/fake-dir", LOOPX_TMPDIR: "/tmp/fake-tmp", LOOPX_BIN: "/tmp/fake-bin" } })`. Scripts observe each variable. Assert each marker contains the real injected value (tier-1 protocol), not the `RunOptions.env` (tier-2) value. Per Spec 9.5 "No name validation beyond string-to-string", `LOOPX_*` keys in `RunOptions.env` are silently overridden by protocol injection. **`LOOPX_TMPDIR` rigor**: matching T-TMP-30 / T-TMP-31, the fixture additionally performs an in-script `stat` of the observed `$LOOPX_TMPDIR` path **during execution** (before the script exits), recording the stat result (exists, is-a-directory) to a marker. The during-run stat is essential because SPEC 7.4 cleanup removes the tmpdir on run completion; a post-run stat would observe absence. Assert: (a) the observed `LOOPX_TMPDIR` marker records the real injected tmpdir path (under `os.tmpdir()` or the test-isolated parent, matching the `loopx-*` naming pattern), **not** `/tmp/fake-tmp`, (b) the during-run stat marker records "exists as a directory" — proving it is the real loopx-created tmpdir, not merely a substituted string. A buggy implementation that string-substituted the protocol value but failed to actually create the tmpdir would fail (b). *(Spec 9.5, 8.3, 7.4)*
+- **T-API-51a2**: Generator-surface counterpart to T-API-51a — all five script-protocol-protected `LOOPX_*` keys supplied via `RunOptions.env` are silently overridden by protocol injection on the `run()` surface. T-API-51a covers all five protocol variables on `runPromise()` (eager-snapshot surface per SPEC 9.2); T-WFDIR-08 covers `LOOPX_WORKFLOW_DIR` alone on `run()` (lazy-snapshot surface per SPEC 9.1); no test currently covers all five protocol variables on `run()` in a single matrix. The two run surfaces have **different snapshot timing** for inherited `process.env`, but the SPEC 8.3 tier-1 protocol-override rule applies identically — a buggy implementation that wired the override correctly on the eager-snapshot `runPromise()` path while losing override on the lazy-snapshot `run()` path for one of the five protocol names (e.g., re-merging tiers at first `next()` in a way that let the user-supplied `RunOptions.env` value reach the child for `LOOPX_TMPDIR` but not for `LOOPX_WORKFLOW`) would pass T-API-51a / T-WFDIR-08 and fail this test. **Setup.** Same five fake values as T-API-51a: build the options object via `Object.defineProperty` (or field-by-field assembly per the section 1.3 construction rule for `LOOPX_*` override variants) so the env value is a plain reference and not a spread source. Place `.loopx/ralph/index.ts` (or `.sh`) that observes each of `LOOPX_BIN`, `LOOPX_PROJECT_ROOT`, `LOOPX_WORKFLOW`, `LOOPX_WORKFLOW_DIR`, `LOOPX_TMPDIR` via `observe-env` into per-name markers, additionally performs an in-script `stat` of the observed `$LOOPX_TMPDIR` path **during execution** (before the script exits) recording the stat result (exists, is-a-directory) to a tmpdir-stat marker — matching T-API-51a's during-run-stat rigor — then emits `stop:true`. **Drive.** `const gen = run("ralph", { env: { LOOPX_WORKFLOW: "fake", LOOPX_PROJECT_ROOT: "/tmp/fake", LOOPX_WORKFLOW_DIR: "/tmp/fake-dir", LOOPX_TMPDIR: "/tmp/fake-tmp", LOOPX_BIN: "/tmp/fake-bin" }, maxIterations: 1 }); for await (const _ of gen) {}` (or equivalent generator drive pattern; the construction rule applies — assemble the env object directly, do not spread). Assert: (a) the `LOOPX_BIN` marker records the real injected loopx-binary path (resolved per SPEC 13's binary-path rules), **not** `/tmp/fake-bin`, (b) the `LOOPX_PROJECT_ROOT` marker records the real injected project-root absolute path, **not** `/tmp/fake`, (c) the `LOOPX_WORKFLOW` marker records `"ralph"` (the real workflow name), **not** `"fake"`, (d) the `LOOPX_WORKFLOW_DIR` marker records the real injected `.loopx/ralph/` absolute path, **not** `/tmp/fake-dir`, (e) the `LOOPX_TMPDIR` marker records the real injected tmpdir path (under `os.tmpdir()` or the test-isolated parent, matching the `loopx-*` naming pattern), **not** `/tmp/fake-tmp`, (f) the during-run tmpdir-stat marker records "exists as a directory" — proving it is the real loopx-created tmpdir, not merely a substituted string (matching T-API-51a's during-run-stat rigor on the generator surface), and (g) the generator settled cleanly (no error). Together with T-API-51a (`runPromise()` eager surface) and T-WFDIR-08 (`LOOPX_WORKFLOW_DIR` alone on `run()`), this closes the protocol-override × five-script-protocol-protected-name matrix on the generator surface. *(Spec 9.5, 9.1, 8.3, 7.4)*
+- **T-API-51b**: `RunOptions.env` overrides local env-file values. Local env file `.env` contains `MYVAR=from-file`. Call `runPromise("ralph", { envFile: ".env", env: { MYVAR: "from-options" }, maxIterations: 1 })`. Script observes `MYVAR`. Assert marker shows `"from-options"`. *(Spec 9.5, 8.3)*
+- **T-API-51c**: `RunOptions.env` overrides global env-file values. Global env file contains `MYVAR=from-global`. Call `runPromise("ralph", { env: { MYVAR: "from-options" }, maxIterations: 1 })`. Assert marker shows `"from-options"`. *(Spec 9.5, 8.3)*
+- **T-API-51d**: `RunOptions.env` overrides inherited `process.env` values. Parent process has `MYVAR=inherited`. Call `runPromise("ralph", { env: { MYVAR: "from-options" }, maxIterations: 1 })`. Assert marker shows `"from-options"`. *(Spec 9.5, 8.3)*
+- **T-API-51e**: Full precedence chain. Inherited `MYVAR=1`, global env file `MYVAR=2`, local env file `MYVAR=3`, `RunOptions.env.MYVAR=4`, protocol variables (unchanged — `MYVAR` is not a protocol name). Script observes `MYVAR`. Assert `"4"` — `RunOptions.env` wins over all lower tiers, and protocol doesn't apply to non-`LOOPX_*` names. *(Spec 9.5, 8.3)*
+- **T-API-51f**: `run()` — full precedence chain on the generator surface. Generator-surface counterpart to T-API-51e (`runPromise()`). T-API-51a–51e cover protocol-override / single-tier overrides on `runPromise()`, and T-API-51a uses `run()` indirectly via `runPromise` semantics, but no test directly exercises the **full four-tier** chain (inherited → global env file → local env file → `RunOptions.env`) on the generator surface. The two run surfaces have different snapshot timing for inherited `process.env` (lazy under `run()` per SPEC 9.1; eager under `runPromise()` per SPEC 9.2), and a buggy implementation that wired `RunOptions.env` precedence correctly on the eager-snapshot `runPromise()` path while losing precedence on the lazy-snapshot `run()` path — for example, by re-merging tiers at first `next()` in a different order than the eager path uses — would pass T-API-51e and fail this test. **Setup.** Configure inherited `process.env.MYVAR=1`, global env file containing `MYVAR=2`, local env file (`-e` equivalent — `RunOptions.envFile` here) containing `MYVAR=3`. Place `.loopx/ralph/index.sh` that observes `MYVAR` via `observe-env` into a marker, then emits `stop:true`. **Drive.** `const gen = run("ralph", { envFile: "<local-envfile-path>", env: { MYVAR: "4" }, maxIterations: 1 }); for await (const _ of gen) {}` (or equivalent generator drive pattern). Assert: (a) the marker records `process.env.MYVAR === "4"` — `RunOptions.env` wins over all three lower tiers on the `run()` surface, matching SPEC 8.3's precedence list (protocol > `RunOptions.env` > local env file > global env file > inherited; `MYVAR` is not a protocol name, so `RunOptions.env` is the effective winner); (b) the generator settled cleanly (no error). Together with T-API-51e (`runPromise()` full chain), this closes the surface asymmetry for `RunOptions.env` precedence under ADR-0004. *(Spec 9.5, 9.1, 8.3)*
+
+##### Snapshot Semantics
+
+- **T-API-52**: `RunOptions.env` is snapshotted at call time. `const e = { MYVAR: "initial" }; const p = runPromise("ralph", { env: e, maxIterations: 1 }); e.MYVAR = "mutated";` Await `p`. Script observes `MYVAR`. Assert marker shows `"initial"` — mutating the original object after `runPromise()` returns has no effect on the running loop. *(Spec 9.5)*
+- **T-API-52a**: `RunOptions.env` snapshot is shallow. `const e = { MYVAR: "initial" }; const gen = run("ralph", { env: e, maxIterations: 1 }); e.NEWVAR = "added"; await gen.next();` Script observes both `MYVAR` and `NEWVAR`. Assert `MYVAR` present with `"initial"` and `NEWVAR` absent — the shallow snapshot captured the initial keys, and the added key is not observed. Paired with T-API-52 (value mutation) to pin down "own enumerable string-keyed properties read once". *(Spec 9.5, 9.1)*
+- **T-API-52b**: `RunOptions.env` snapshot timing under `run()` is eager at call time. `const e = { MYVAR: "A" }; const gen = run("ralph", { env: e, maxIterations: 1 }); e.MYVAR = "B"; await gen.next();` Script observes `MYVAR`. Per Spec 9.5 "Shape ... Lifetime. Entries are captured synchronously at call time as a shallow copy" — the snapshot is taken at `run()` call time, not at first `next()`. Assert marker shows `"A"`. This test intentionally differs from T-API-09b (which covers inherited `process.env`, captured lazily) to prove `RunOptions.env` has *eager* snapshot semantics while `process.env` has *lazy* semantics under `run()`. *(Spec 9.5, 9.1)*
+- **T-API-52c**: `run()` — `RunOptions.env` enumerable getter is invoked exactly once at call time (before `run()` returns), and the captured value reaches the spawned script even after the backing state mutates. SPEC 9.5: "Entries are captured synchronously at call time as a shallow copy — loopx reads the supplied object's own enumerable string-keyed properties once. The capture runs at the `run()` / `runPromise()` call site …". T-API-52 / T-API-52a / T-API-52b cover the **outer-property** snapshot semantics with plain assignments (no getters), so they do not directly observe the "own enumerable string-keyed properties **read once at call time**" contract on the per-entry getter axis — a buggy implementation that deferred entry-getter reads to first `next()` (or re-invoked them per spawn) would still pass T-API-52 / T-API-52a / T-API-52b but fail this test. **Setup.** `let count = 0; let backing = "initial"; const env = {}; Object.defineProperty(env, "MYVAR", { enumerable: true, configurable: true, get() { count += 1; return backing; } });` Place `.loopx/ralph/index.sh` that observes `MYVAR` via `observe-env` and emits `stop:true`. **Drive.** `const gen = run("ralph", { env, maxIterations: 1 });` — at this point, before any `next()`, capture `count` into a local: `const countAfterRun = count;` Mutate the backing state: `backing = "mutated"; const countAfterMutate = count;` Then `await gen.next(); /* yields the script's Output */ await gen.next(); /* settles */;` Capture `count` once more: `const countAfterSettle = count;` Assert: (a) `countAfterRun === 1` — the getter fired exactly once, **synchronously at the `run()` call site**, before the iteration loop began (proves the eager-capture clause of SPEC 9.5); (b) `countAfterMutate === 1` — mutating the backing state after `run()` returned did not re-invoke the getter (the snapshot is frozen); (c) the `observe-env` marker for `MYVAR` records `{ "present": true, "value": "initial" }` — the spawned script saw the captured value, not the post-call mutation; (d) `countAfterSettle === 1` — driving the generator to settlement did not re-invoke the getter (no per-spawn re-read). A buggy implementation that read the getter lazily at first `next()` would satisfy (b) and (c) but fail (a) (`countAfterRun === 0`); a buggy implementation that re-invoked the getter per spawn would fail (b)/(d). Together with T-API-52 / T-API-52a / T-API-52b, this test pins down the per-entry getter side of "read once at call time" on the `run()` surface. *(Spec 9.5, 9.1)*
+- **T-API-52d**: `runPromise()` counterpart to T-API-52c — `RunOptions.env` enumerable getter is invoked exactly once **synchronously before `runPromise()` returns**, and the captured value is observed by every script across multiple iterations even after the backing state mutates. SPEC 9.2 / 9.5: snapshot semantics are identical to `run()` except the snapshot fires at the `runPromise()` call site. T-API-52 covers the outer-property snapshot under `runPromise()` with a plain object assignment (no getter); this test pins down the per-entry-getter axis on the `runPromise()` surface. **Setup.** `let count = 0; let backing = "initial"; const env = {}; Object.defineProperty(env, "MYVAR", { enumerable: true, configurable: true, get() { count += 1; return backing; } });` Place `.loopx/ralph/index.sh` that observes `MYVAR` via `observe-env` and writes a per-iteration marker (so each spawn's observation is distinguishable). Drive a multi-iteration loop (e.g., the script emits `stop: false` for two iterations and `stop: true` on the third — `maxIterations: 3`). **Drive.** `const p = runPromise("ralph", { env, maxIterations: 3 }); const countAfterCall = count; backing = "mutated"; const countAfterMutate = count; const outputs = await p; const countAfterResolve = count;` Assert: (a) `countAfterCall === 1` — the getter fired exactly once **synchronously at the `runPromise()` call site**, before the function returned (proves the eager-capture clause for `runPromise()` — `runPromise` snapshots eagerly per SPEC 9.2 vs. `run`'s call-time capture per T-API-52b); (b) `countAfterMutate === 1` — synchronous mutation after `runPromise()` returned did not re-invoke the getter; (c) every per-iteration `observe-env` marker records `{ "present": true, "value": "initial" }` (three iterations, three markers, all `"initial"`) — the spawned scripts saw the captured value despite the post-call mutation, and the value was reused across spawns; (d) `countAfterResolve === 1` — the getter was not re-invoked between spawns (per-spawn re-reads would have produced `count >= 3`). A buggy implementation that re-read getters per spawn would fail (d) and produce `count === 3` (one read per iteration); an implementation that read the getter lazily after the await point would fail (a). Together with T-API-52c (`run()` surface), this test closes the per-entry-getter / snapshot-once / no-re-read coverage across both API surfaces. *(Spec 9.5, 9.2)*
+- **T-API-52e**: `RunOptions.env` proxy-success variant — `ownKeys` is invoked exactly once at snapshot time, the `get` trap is invoked exactly once per included key, and neither is re-invoked across iterations. Companion to T-API-52c / T-API-52d for the **proxy** snapshot path. SPEC 9.5 specifies `RunOptions.env` is read once at call time ("loopx reads the supplied object's own enumerable string-keyed properties once") and value reads use ordinary `[[Get]]` semantics ("After loopx has identified the included own enumerable string-keyed keys, it reads each included key's value using ordinary ECMAScript property `[[Get]]` semantics, equivalent to `env[key]`, exactly once during the call-time snapshot"). The per-entry-getter axis is covered by T-API-52c / T-API-52d; the **proxy enumeration and value-read** axis (`ownKeys` and `get` traps) is not otherwise directly pinned down on the success path. T-API-62f / T-API-62f3 cover the throwing-trap **failure** path; a successful proxy must also be enumerated and value-read exactly once — a buggy implementation that re-invoked `ownKeys` or `get` per spawn would silently amplify trap calls without surfacing as an error. **Setup.** `let ownKeysCount = 0; let getCount = 0; let descCount = 0; const valueGetCounts = new Map(); const target = { MYVAR: "initial", OTHERVAR: "second" }; const env = new Proxy(target, { ownKeys(t) { ownKeysCount += 1; return Reflect.ownKeys(t); }, getOwnPropertyDescriptor(t, key) { descCount += 1; return Reflect.getOwnPropertyDescriptor(t, key); }, get(t, key) { if (typeof key === "string") { getCount += 1; valueGetCounts.set(key, (valueGetCounts.get(key) ?? 0) + 1); } return Reflect.get(t, key); } });` Place `.loopx/ralph/index.sh` observing `MYVAR` and `OTHERVAR` via `observe-env`, emitting `stop: false` for two iterations and `stop: true` on the third. **Parameterize over both API surfaces.** Variant (a) `run()`: `const gen = run("ralph", { env, maxIterations: 3 }); const ownKeysAfterCall = ownKeysCount; const getAfterCall = getCount; const valueGetSnapshot = new Map(valueGetCounts); while (!(await gen.next()).done) {} const ownKeysAfterDone = ownKeysCount; const getAfterDone = getCount; const valueGetAfterDone = new Map(valueGetCounts);` Variant (b) `runPromise()`: `const p = runPromise("ralph", { env, maxIterations: 3 }); const ownKeysAfterCall = ownKeysCount; const getAfterCall = getCount; const valueGetSnapshot = new Map(valueGetCounts); await p; const ownKeysAfterDone = ownKeysCount; const getAfterDone = getCount; const valueGetAfterDone = new Map(valueGetCounts);` Assert per variant: (1) **`ownKeysAfterCall === 1`** — the `ownKeys` trap was invoked exactly once during the call-time snapshot (a single enumeration), satisfying SPEC 9.5's "read once" contract on the enumeration axis directly. (2) **`ownKeysAfterDone === ownKeysAfterCall`** — the trap was not re-invoked between or during the three iterations. (3) Every iteration's `observe-env` marker shows `MYVAR = "initial"` and `OTHERVAR = "second"` (the snapshot values reached every spawn). (4) **`getAfterCall === 2`** — the `get` trap was invoked exactly once per included string key (`MYVAR` and `OTHERVAR`) during the call-time snapshot, satisfying SPEC 9.5's `[[Get]]`-semantics-exactly-once contract on the value-read axis. (5) **`valueGetSnapshot.get("MYVAR") === 1` and `valueGetSnapshot.get("OTHERVAR") === 1`** — per-key call count is exactly one. (6) **`getAfterDone === getAfterCall`** and **`valueGetAfterDone.get(key) === valueGetSnapshot.get(key)` for each enumerable string key** — no additional `get`-trap reads across iterations / spawns (the no-per-spawn-re-read invariant on the value axis). (7) **`descCount` is left as a non-asserted observation** — SPEC 9.5 explicitly leaves the enumerability-determination strategy implementation-defined ("The strategy used to determine enumerability may invoke descriptor-related proxy traps and remains otherwise implementation-defined"); `getOwnPropertyDescriptor` may legitimately fire a different number of times depending on whether the implementation uses `Object.keys` (which calls `[[OwnPropertyKeys]]` then filters by descriptor) vs. `Reflect.ownKeys` (which does not invoke the descriptor trap) vs. a `for...in` audit. The strict equalities (1)–(6) are the load-bearing assertions: a buggy implementation that re-invoked `ownKeys` per spawn would fail (2); an implementation that snapshot-time-enumerated more than once would fail (1); a descriptor-based-extraction implementation that skipped `[[Get]]` would observe `getAfterCall === 0` and fail (4); a per-spawn `get` re-read would fail (6). T-API-52a / T-API-52b cover plain-object snapshots; T-API-52c / T-API-52d cover per-entry getters; this test pins down the proxy-trap axis with exact call counts on both the `ownKeys` and `get` axes per SPEC 9.5's normative `[[Get]]`-semantics contract. *(Spec 9.5, 9.1, 9.2)*
+- **T-API-52e2**: `RunOptions.env` proxy-success variant — non-`ownKeys` trap coverage. Companion to T-API-52e covering the success-path no-per-spawn-re-read invariant for the `getOwnPropertyDescriptor` and `get` traps when those are the **only** custom traps installed. T-API-52e covers all three traps simultaneously; this test pins down the success-path no-re-read behavior in two narrow configurations where `ownKeys` is the default `Reflect.ownKeys` (so `ownKeysCount` is not directly observable on the proxy). **Parameterize over two trap configurations:** variant (a) **only `getOwnPropertyDescriptor` is custom-trapped** — `let descCount = 0; const target = { MYVAR: "initial", OTHERVAR: "second" }; const env = new Proxy(target, { getOwnPropertyDescriptor(t, key) { descCount += 1; return Reflect.getOwnPropertyDescriptor(t, key); } });` Drive `runPromise("ralph", { env, maxIterations: 3 })` against an `observe-env` fixture, capture `descCount` after `runPromise()` returns and after the promise resolves. Assert: (1) `descAfterDone === descAfterCall` — descriptor trap was not re-invoked across iterations / spawns, even if it fires more than once during the snapshot (SPEC 9.5 leaves the enumerability-determination strategy implementation-defined, so the per-call count is not asserted); (2) every iteration observes `MYVAR = "initial"` and `OTHERVAR = "second"` (snapshot values reached every spawn). Variant (b) **only `get` is custom-trapped** — `let getCount = 0; const valueGetCounts = new Map(); const env = new Proxy(target, { get(t, key) { if (typeof key === "string") { getCount += 1; valueGetCounts.set(key, (valueGetCounts.get(key) ?? 0) + 1); } return Reflect.get(t, key); } });` Drive the same `runPromise("ralph", { env, maxIterations: 3 })` and capture counts on the same schedule. Assert per SPEC 9.5's `[[Get]]`-semantics-exactly-once contract: (1) **`getAfterCall === 2`** — the `get` trap was invoked exactly once per included string key (`MYVAR` and `OTHERVAR`) during the call-time snapshot; (2) **`valueGetSnapshot.get("MYVAR") === 1` and `valueGetSnapshot.get("OTHERVAR") === 1`** — per-key call count is exactly one; (3) **`getAfterDone === getAfterCall`** and **`valueGetAfterDone.get(key) === valueGetSnapshot.get(key)` for each enumerable string key** — no per-spawn re-read amplification across iterations; (4) every iteration observes the snapshot values `MYVAR = "initial"` and `OTHERVAR = "second"` (the captured snapshot values reach every spawn). A buggy implementation using descriptor-based extraction (`getCount === 0`) would fail (1); an implementation that re-read per spawn would fail (3). Together with T-API-52e (combined-trap configuration), this completes the success-path no-per-spawn-re-read coverage axis across all three proxy-trap shapes (`ownKeys`-only, `getOwnPropertyDescriptor`-only, `get`-only). *(Spec 9.5, 9.1, 9.2)*
+
+##### Invalid Shape
+
+- **T-API-53**: `RunOptions.env = null` → generator throws on first `next()` (invalid shape). `run("ralph", { env: null as any })` returns a generator; `.next()` throws with an error mentioning invalid `env`. *(Spec 9.5)*
+- **T-API-53a**: `RunOptions.env = []` (array) → generator throws on first `next()`. Arrays are rejected per Spec 9.5 "non-null, non-array, non-function object". *(Spec 9.5)*
+- **T-API-53b**: `RunOptions.env = () => {}` (function) → generator throws on first `next()`. *(Spec 9.5)*
+- **T-API-53c**: `RunOptions.env = "string"` → generator throws on first `next()`. *(Spec 9.5)*
+- **T-API-53d**: `RunOptions.env = 42` → generator throws on first `next()`. *(Spec 9.5)*
+- **T-API-54**: Non-string entry value → generator throws on first `next()`. `run("ralph", { env: { MYVAR: 42 as any } })` — non-string value is rejected. *(Spec 9.5)*
+- **T-API-54a**: `undefined` entry value → generator throws on first `next()`. `run("ralph", { env: { MYVAR: undefined as any } })`. Per Spec 9.5, all own enumerable string-keyed entries must have string values; `undefined` is not a string. *(Spec 9.5)*
+- **T-API-54b**: `null` entry value → generator throws on first `next()`. *(Spec 9.5)*
+- **T-API-54c**: Object entry value → generator throws on first `next()`. *(Spec 9.5)*
+- **T-API-55**: `runPromise` equivalents for invalid shapes — all invalid `RunOptions.env` shapes reject the promise. Parameterized across null, array, function, string, number, and non-string entry values. *(Spec 9.5, 9.2)*
+
+##### Invalid Shape Under `maxIterations: 0`
+
+SPEC 9.5 explicitly states: "`RunOptions.env` shape validation (invalid object types, non-string values, snapshot-time throws) is independent of spawning and surfaces under `maxIterations: 0` just as under any other iteration count." Existing `maxIterations: 0` tests (T-API-08a–08r) cover target / envFile / global-env / sibling-validation failures under that short-circuit, and T-API-53–55 cover `RunOptions.env` shape validation under normal iteration counts, but the combination is not explicitly pinned down. A buggy implementation could short-circuit `maxIterations: 0` before reading the `env` option and pass all those tests without exercising the SPEC 9.5 rule.
+
+- **T-API-55a**: `run()` — **full invalid `env` shape and entry-value matrix** under `maxIterations: 0`. SPEC 9.5 explicitly says `RunOptions.env` shape validation "is independent of spawning and surfaces under `maxIterations: 0` just as under any other iteration count" — both the invalid-object-type branch (T-API-53–53d) and the non-string-entry-value branch (T-API-54–54c) must surface under the zero-iteration short-circuit. T-API-55b covers the same matrix on the `runPromise()` surface; together they pin down both axes of the shape-validation rule across both API surfaces. **Parameterize over the full SPEC 9.5 invalid-`env` enumeration**: variant (a) **`env: null`** (`run("ralph", { maxIterations: 0, env: null as any })`); variant (b) **`env: []`** (array); variant (c) **`env: () => {}`** (function); variant (d) **`env: "string"`**; variant (e) **`env: 42`** (primitive number); variant (f) **non-string entry value — number**: `env: { MYVAR: 42 as any }`; variant (g) **non-string entry value — `undefined`**: `env: { MYVAR: undefined as any }`; variant (h) **non-string entry value — `null`**: `env: { MYVAR: null as any }`; variant (i) **non-string entry value — object**: `env: { MYVAR: { nested: "value" } as any }`; variant (j) **non-string entry value — function**: `env: { MYVAR: (() => "value") as any }`. For each variant, drive `const gen = run("ralph", { maxIterations: 0, env: <variant> }); await expect(gen.next()).rejects.toThrow(/env/i);` Assert per variant: (a) the first `next()` throws an error mentioning invalid `env`, (b) the error surfaces as a shape-validation error — **not** the silent zero-iteration short-circuit (which would resolve `{ done: true }` per T-API-08a etc.) and **not** a spawn-failure error, (c) no child is spawned (no marker file written), and (d) no `LOOPX_TMPDIR` was created (consistent with SPEC 7.1 step 6 / SPEC 7.4 — tmpdir is not created under `maxIterations: 0`, and shape-validation errors fire before tmpdir creation). A buggy implementation that short-circuited `maxIterations: 0` before reading the `env` option would fail on every variant; an implementation that gated the validation only on object-type (rejecting variants (a)–(e)) or only on entry-value (rejecting variants (f)–(j)) would fail the other half. Together with T-API-55c (throwing-getter / proxy-trap branch on the `run()` surface), this completes coverage for SPEC 9.5's three explicitly-enumerated `env` validation branches — invalid object type, invalid entry value, snapshot-time throws — on the generator surface under `maxIterations: 0`. *(Spec 9.1, 9.5)*
+- **T-API-55b**: `runPromise()` — **full invalid `env` shape and entry-value matrix** under `maxIterations: 0`. `runPromise()`-surface counterpart to T-API-55a, parameterized over the same ten variants (a)–(j). For each variant, drive `await expect(runPromise("ralph", { maxIterations: 0, env: <variant> })).rejects.toThrow(/env/i);` Assert per variant: (a) the promise rejects with a shape-validation error mentioning invalid `env`, (b) the rejection is **not** the resolved-with-`[]` zero-iteration short-circuit (which would mean the `env` snapshot was skipped) and **not** a spawn-failure error, (c) no child is spawned, and (d) no `LOOPX_TMPDIR` was created. Together with T-API-55a (generator surface, full matrix) and T-API-55d (throwing-getter / proxy-trap branch on the `runPromise()` surface), this completes coverage for SPEC 9.5's three explicitly-enumerated `env` validation branches — invalid object type, invalid entry value, snapshot-time throws — on both API surfaces under `maxIterations: 0`. *(Spec 9.2, 9.5)*
+- **T-API-55c**: `run("ralph", { maxIterations: 0, env: <throwing-getter-or-proxy> })` → generator throws on first `next()` with the captured snapshot-time exception. SPEC 9.5 explicitly enumerates "snapshot-time throws" alongside invalid object types and non-string values as `RunOptions.env` validation that "is independent of spawning and surfaces under `maxIterations: 0` just as under any other iteration count." T-API-55a covers the invalid-object-type branch and T-API-55b covers the non-string-value branch under `maxIterations: 0`, but the **snapshot-time-throws** branch — which SPEC 9.5 names explicitly — is not currently covered under zero iterations. T-API-62e (throwing enumerable getter inside `options.env`) and T-API-62f (throwing proxy `ownKeys` trap on `options.env`) cover snapshot-time throws under normal iteration counts, but the combination with `maxIterations: 0` is not. A buggy implementation that short-circuited `maxIterations: 0` before reading the `env` proxy traps / enumerable getters would pass T-API-55a / T-API-55b (object-type and value-type validation gates) but skip the snapshot-time-throw path entirely. **Parameterize over four variants:** variant (a) **throwing enumerable getter inside `options.env`** — `const env = { A: "a" }; Object.defineProperty(env, "B", { enumerable: true, get() { throw new Error("env-entry-getter-boom"); } }); const gen = run("ralph", { maxIterations: 0, env });`; variant (b) **throwing proxy `ownKeys` trap on `options.env`** — `const env = new Proxy({ A: "a" }, { ownKeys() { throw new Error("ownKeys-trap-boom"); } }); const gen = run("ralph", { maxIterations: 0, env });`; variant (c) **throwing `options.env` getter on the options object itself** — build the **final options object directly** so the throwing getter is preserved as a getter on the object passed to `run()` rather than being invoked at the call site by an object-spread (see "Test-construction sanity for getter/proxy variants" in section 1.3). Construct: `const opts: any = { maxIterations: 0 }; Object.defineProperty(opts, "env", { enumerable: true, get() { throw new Error("options-env-getter-boom"); } }); const gen = run("ralph", opts);`. **Do not use `{ ...opts, maxIterations: 0 }` here**: spreading `opts` invokes the throwing `env` getter in the test harness before `run()` is called, which surfaces the exception at the test call site rather than letting loopx capture it via the SPEC 9.5 snapshot path — invalidating the assertion. The third variant is the SPEC 9.5 snapshot-time-throw class that fires when the **outer** `options.env` property access throws — distinct from variant (a) (throwing entry getter on the env object's own property) and from variant (b) (throwing proxy trap during enumeration of the env object); variant (d) **throwing `Proxy` `get` trap on an included `options.env` key** — `const env = new Proxy({ KEY: "value" }, { ownKeys() { return ["KEY"]; }, getOwnPropertyDescriptor() { return { enumerable: true, configurable: true }; }, get() { throw new Error("get-trap-boom"); } }); const gen = run("ralph", { maxIterations: 0, env });` (the proxy is the value of `options.env`, not a getter on the options object itself, so reading `options.env` does not trigger any trap during construction; SPEC 9.5 normatively specifies ordinary `[[Get]]` semantics for value reads on included keys, so the throwing `get` trap fires inside loopx's snapshot pass when it reads `env[key]` per the same `[[Get]]` clause that T-API-62f3 / T-API-62h9 pin under non-zero iterations; this variant extends that branch to the `maxIterations: 0` short-circuit, structurally distinct from variant (b) which exercises the `ownKeys` enumeration trap rather than the value-read `get` trap). T-API-62 (throwing getter on options' `env` property under `maxIterations >= 1`) covers variant (c)'s same surface under non-zero iterations; this variant pins down the same branch under `maxIterations: 0`. For each variant, drive `await expect(gen.next()).rejects.toThrow(/env-entry-getter-boom|ownKeys-trap-boom|get-trap-boom|options-env-getter-boom/);` Assert per variant: (a) the first `next()` throws the snapshot-time exception (the captured `Error` from the getter / trap), (b) the error surfaces as an option-snapshot error — **not** a spawn-failure error and not the silent zero-iteration short-circuit, (c) no child is spawned (no marker file), and (d) no `LOOPX_TMPDIR` was created (consistent with SPEC 7.1 step 6 / SPEC 7.4 — tmpdir is not created under `maxIterations: 0`, and snapshot-time errors fire before tmpdir creation). Together with T-API-55a (object-type validation under `maxIterations: 0`) and T-API-55b (value-type validation under `maxIterations: 0`), this test closes the third branch of SPEC 9.5's "shape validation ... independent of spawning" enumeration — snapshot-time throws — on the generator surface across all four snapshot-throw sub-paths (inner-entry-getter, inner-proxy-`ownKeys`-trap, inner-proxy-`get`-trap, outer-options-env-getter). *(Spec 9.1, 9.5)*
+- **T-API-55d**: `runPromise("ralph", { maxIterations: 0, env: <throwing-getter-or-proxy> })` → rejects with the captured snapshot-time exception. `runPromise()` counterpart to T-API-55c. Same SPEC 9.5 contract: "snapshot-time throws" is one of the three explicitly-enumerated `RunOptions.env` validation branches that surface under `maxIterations: 0`. T-API-55b covers the non-string-value branch on the `runPromise()` surface; this test extends the coverage to the snapshot-time-throws branch on the same surface. **Parameterize over the same four variants as T-API-55c** (throwing enumerable getter inside `options.env`, throwing proxy `ownKeys` trap on `options.env`, throwing `options.env` getter on the options object itself, and throwing `Proxy` `get` trap on an included `options.env` key). For variant (c), build the **final options object directly** so the throwing getter is preserved as a getter on the object passed to `runPromise()` rather than being invoked at the call site by an object-spread (see "Test-construction sanity for getter/proxy variants" in section 1.3). Construct: `const opts: any = { maxIterations: 0 }; Object.defineProperty(opts, "env", { enumerable: true, get() { throw new Error("options-env-getter-boom"); } }); await expect(runPromise("ralph", opts)).rejects.toThrow(/options-env-getter-boom/);`. **Do not use `{ ...opts, maxIterations: 0 }` here**: spreading `opts` invokes the throwing `env` getter in the test harness before `runPromise()` is called, which surfaces the exception at the test call site rather than letting loopx capture it via the SPEC 9.5 snapshot path. For variant (d), construct the proxy as in T-API-55c — `const env = new Proxy({ KEY: "value" }, { ownKeys() { return ["KEY"]; }, getOwnPropertyDescriptor() { return { enumerable: true, configurable: true }; }, get() { throw new Error("get-trap-boom"); } });` — and pass it as `options.env`: `await expect(runPromise("ralph", { maxIterations: 0, env })).rejects.toThrow(/get-trap-boom/);` (the proxy is a plain object reference on `options.env`, so reading `options.env` does not trigger any trap during construction; SPEC 9.5 normatively requires ordinary `[[Get]]` semantics for value reads on included keys, so the throwing `get` trap fires inside loopx's snapshot pass per the same clause T-API-62f3 / T-API-62h9 pin under non-zero iterations, and this variant pins the same surface under the `maxIterations: 0` short-circuit). For each of the env-entry / proxy variants (a) and (b), drive `await expect(runPromise("ralph", { maxIterations: 0, env })).rejects.toThrow(/env-entry-getter-boom|ownKeys-trap-boom/);` Assert per variant: (a) the promise rejects with the snapshot-time exception (the captured `Error` from the getter / trap), (b) the rejection is an option-snapshot error — not a spawn-failure error and not the resolved-with-`[]` zero-iteration short-circuit (which would mean the `env` snapshot was skipped), (c) no child is spawned, and (d) no `LOOPX_TMPDIR` was created. Together with T-API-55c, this completes coverage for the "snapshot-time throws under `maxIterations: 0`" branch across both API surfaces and across all four snapshot-throw sub-paths (inner-entry-getter, inner-proxy-`ownKeys`-trap, inner-proxy-`get`-trap, outer-options-env-getter), matching the existing coverage pattern of T-API-55a / T-API-55b for the other two SPEC 9.5 enumerated branches. *(Spec 9.2, 9.5)*
+
+##### Other Invalid Options Under `maxIterations: 0`
+
+SPEC 9.1 / 9.5 specify that the option-snapshot pass runs at the call site for every `RunOptions` field, and SPEC 9.5 makes shape validation independent of spawning ("`RunOptions.env` shape validation … surfaces under `maxIterations: 0` just as under any other iteration count"). The same independence applies to the other option fields' shape validation: invalid `options` wrapper, invalid `options.signal`, non-string `cwd` / `envFile`, throwing `cwd` / `envFile` getters — none of these depend on a spawn step, so all must surface under `maxIterations: 0` just as under any other iteration count. T-API-55a–55d pin the rule down for `RunOptions.env`; the tests below pin it down for the remaining option fields. Existing T-API-08a–08r cover `maxIterations: 0` validation for target / envFile-load / global-env / sibling-validation paths but do not exercise the option-shape-validation paths under zero iterations, leaving a buggy implementation that short-circuits `maxIterations: 0` before reading the non-`env` option fields uncaught beyond the env axis.
+
+- **T-API-55e**: `run()` and `runPromise()` — invalid `options` **wrapper** is rejected as an option-snapshot error before any spawn or tmpdir-creation step runs. **Important framing.** This test belongs to the "Other Invalid Options Under `maxIterations: 0`" section because it closes the same "an implementation that short-circuited `maxIterations: 0` could have skipped the option-shape gate" gap that T-API-55a–55d / 55f / 55g / 55h close for **field-level** validation, but the `maxIterations: 0` framing applies to it differently from those tests. Per SPEC 9.5, an invalid `options` wrapper (`null`, an array, a function, a primitive) cannot itself carry a `maxIterations` field; wrapper-shape validation happens before field-level processing, so the zero-iteration short-circuit is **not applicable** to this test — the contract under exercise is wrapper-shape rejection in isolation, not wrapper rejection "under" `maxIterations: 0`. T-API-55a–55d / 55f / 55g / 55h pin down the field-level "validation runs even when no iteration would have run" rule for `env`, `signal`, `cwd`, `envFile`; this test pins down the wrapper-level "wrapper-shape validation runs **before** any field-level processing" rule that those field-level tests presuppose. **Setup.** Use a **valid project** with a valid `.loopx/ralph/index.sh` script — no other pre-iteration condition is engineered to fail. Per SPEC 9.3 "Pinned pre-iteration priority", relative priority among invalid `options`, target argument / target syntax validation, `.loopx/` discovery failures, env-file loading errors, target resolution errors, and tmpdir-creation errors is **implementation-defined**, so the test must not combine the invalid wrapper with another competing pre-iteration failure (a previous version of this test paired `":target"` syntax-invalid with no `.loopx/` discovery failure, asserting wrapper-shape rejection wins — which over-pins implementation-defined priority). **Parameterize over both run surfaces × the SPEC 9.5 invalid-`options` enumeration** (null, array, function — the same variants pinned by T-API-61 / T-API-61a / T-API-61b / T-API-61d / T-API-61e under non-zero iterations). For each surface × variant, drive: variant (a) `null`: `run("ralph", null as any)` / `runPromise("ralph", null as any)`; variant (b) `[]` (array): `run("ralph", [] as any)` / `runPromise("ralph", [] as any)`; variant (c) `() => {}` (function): `run("ralph", (() => {}) as any)` / `runPromise("ralph", (() => {}) as any)`. With a valid project and valid target there are no other pre-iteration failures to compete; the only conforming surface is the option-snapshot wrapper-shape rejection. For each surface, assert per variant: (a) the first `next()` throws / the promise rejects with an invalid-`options`-shape error, (b) the error surfaces as an option-snapshot error — **not** a spawn-failure error, (c) no child is spawned, and (d) no `LOOPX_TMPDIR` was created (consistent with SPEC 7.1 step 6 / SPEC 7.4 — tmpdir is not created when pre-iteration fails). T-API-61 / 61a / 61b / 61d / 61e cover the same wrapper shapes under default iterations with non-zero iteration counts; this test pins down that the wrapper-shape rejection still surfaces when the rest of the pre-iteration sequence is otherwise valid, closing the "an implementation that short-circuited `maxIterations: 0` early in the option-snapshot pass could have skipped the wrapper-shape gate" gap without depending on implementation-defined priority among competing pre-iteration failures. *(Spec 9.1, 9.2, 9.3, 9.5)*
+- **T-API-55f**: `run()` and `runPromise()` — invalid `options.signal` rejects under `maxIterations: 0`. **Parameterize over both run surfaces × the SPEC 9.5 invalid-`signal` enumeration** (the same variants pinned by T-API-64 family under normal iteration counts: a string `"not-a-signal"`, a number `42`, a plain object missing `addEventListener`, a plain object missing `aborted`, a plain object whose `addEventListener` is not a function, a plain object whose `addEventListener` throws when invoked). For each surface × variant, drive `run("ralph", { maxIterations: 0, signal: <variant> as any })` / `runPromise("ralph", { maxIterations: 0, signal: <variant> as any })`. Assert per surface × variant: (a) the first `next()` throws / the promise rejects with an invalid-`signal`-shape error, (b) the error surfaces as an option-snapshot error — **not** the silent zero-iteration short-circuit and **not** an abort error (per SPEC 9.3, an invalid `options.signal` "captures no signal and does not enter this pathway"), (c) no child is spawned, and (d) no `LOOPX_TMPDIR` was created. SPEC 9.1 says `options.signal` is read first in the option-snapshot pass; this test pins down that the read still happens (and rejects) under `maxIterations: 0`. A buggy implementation that short-circuited `maxIterations: 0` before reading `signal` would silently resolve / settle without error, failing assertion (a). *(Spec 9.1, 9.2, 9.3, 9.5)*
+- **T-API-55g**: `run()` and `runPromise()` — non-string `cwd` and non-string `envFile` reject under `maxIterations: 0`. **Parameterize over both run surfaces × {`cwd`, `envFile`} × the SPEC 9.5 invalid-string enumeration** (number `42`, boolean `true`, object `{}`, array `[]`, function `() => {}`, null — the same variants the field-shape validators reject under non-zero iterations). For each surface × field × variant, drive `run("ralph", { maxIterations: 0, [field]: <variant> as any })` / `runPromise("ralph", { maxIterations: 0, [field]: <variant> as any })`. Assert per surface × field × variant: (a) the first `next()` throws / the promise rejects with a non-string-`<field>`-shape error mentioning the field name, (b) the error surfaces as an option-snapshot error — **not** the silent zero-iteration short-circuit and **not** a project-root-resolution / env-file-loading error (because the field never passes shape validation, neither downstream step runs), (c) no child is spawned, and (d) no `LOOPX_TMPDIR` was created. SPEC 9.5 says `cwd` and `envFile`, when present and not `undefined`, must be strings; SPEC 9.3's "Pinned pre-iteration priority" says non-string `cwd` / `envFile` surface before the four project-root-dependent failures. Under `maxIterations: 0` the project-root-dependent failures don't fire (no spawn), but the field-shape validation must still run because it is independent of spawning per the SPEC 9.5 generalization. A buggy implementation that short-circuited `maxIterations: 0` before reading `cwd` / `envFile` would silently resolve / settle without error. *(Spec 9.1, 9.2, 9.3, 9.5)*
+- **T-API-55h**: `run()` and `runPromise()` — throwing `cwd` and throwing `envFile` getters reject under `maxIterations: 0`. **Parameterize over both run surfaces × {`cwd`, `envFile`}**. For each surface × field, build the **final options object directly** so the throwing getter is preserved as a getter on the object passed to `run()` / `runPromise()` rather than being invoked at the call site by an object-spread (see "Test-construction sanity for getter/proxy variants" in section 1.3). Construct: `const opts: any = { maxIterations: 0 }; Object.defineProperty(opts, "<field>", { enumerable: true, get() { throw new Error("<field>-getter-boom"); } });` Drive `await expect(run("ralph", opts).next()).rejects.toThrow(/<field>-getter-boom/);` / `await expect(runPromise("ralph", opts)).rejects.toThrow(/<field>-getter-boom/);`. **Do not use `{ ...opts, maxIterations: 0 }` here**: spreading `opts` invokes the throwing field getter in the test harness before `run()` / `runPromise()` is called, which surfaces the exception at the test call site rather than letting loopx capture it via the SPEC 9.5 snapshot path — invalidating the assertion. Assert per surface × field: (a) the first `next()` throws / the promise rejects with the captured snapshot-time exception, (b) the error surfaces as an option-snapshot error — **not** the silent zero-iteration short-circuit and **not** a project-root-resolution / env-file-loading error, (c) no child is spawned, and (d) no `LOOPX_TMPDIR` was created. T-API-62b / T-API-62c cover throwing `cwd` / `envFile` getters under non-zero iterations; this test extends the coverage to `maxIterations: 0`, mirroring the T-API-55c / T-API-55d snapshot-time-throw pattern for `env`. A buggy implementation that short-circuited `maxIterations: 0` before invoking the option-field getters would silently resolve / settle, failing assertion (a). Together with T-API-55e (invalid wrapper), T-API-55f (invalid signal), T-API-55g (non-string cwd / envFile), and T-API-55a–55d (env shape / value / snapshot-time-throw), this completes coverage for the SPEC 9.5 generalization that **all** option-shape validation surfaces under `maxIterations: 0` independent of spawning, across every `RunOptions` field. *(Spec 9.1, 9.2, 9.5)*
+
+##### Inherited / Symbol / Non-Enumerable Keys
+
+- **T-API-56**: Inherited keys on the options.env object are ignored. `const proto = { INHERITED: "proto-val" }; const e = Object.create(proto); e.OWN = "own-val"; runPromise("ralph", { env: e, maxIterations: 1 })`. Script observes both. Assert `OWN` present with `"own-val"` and `INHERITED` absent — loopx reads only own enumerable string-keyed properties. *(Spec 9.5)*
+- **T-API-56a**: Symbol-keyed entries are ignored. `const sym = Symbol("SYM"); const e = { OWN: "own-val", [sym]: "sym-val" }; runPromise("ralph", { env: e, maxIterations: 1 })`. Script observes `OWN` and (via TS `Object.getOwnPropertySymbols` or simply observing all `LOOPX_`-free env keys) asserts that no symbol-derived key leaked into the child env. Mainly: `OWN` is present, and the child env has no `SYM`-like stringified key. *(Spec 9.5)*
+- **T-API-56b**: Non-enumerable string-keyed entries are ignored. `const e = {}; Object.defineProperty(e, "HIDDEN", { value: "hidden-val", enumerable: false }); e.VISIBLE = "visible-val"; runPromise("ralph", { env: e, maxIterations: 1 })`. Script observes both. Assert `VISIBLE` present, `HIDDEN` absent. *(Spec 9.5)*
+- **T-API-56c**: Null-prototype `options.env` (`Object.create(null)`) is accepted as a valid env shape — own enumerable string-keyed entries reach the spawned script. SPEC 9.5 specifies the `env` shape as "any non-null, non-array, non-function object whose own enumerable string-keyed entries all have string values" — same structural-not-nominal contract as the parent `options` shape (T-API-61i). A null-prototype env object lacks `Object.prototype` (no `hasOwnProperty`, no `toString`); a buggy implementation that uses `instanceof Object` to validate the env shape (which fails for null-prototype objects) or that calls `env.hasOwnProperty(...)` directly (which throws `TypeError`) instead of the prototype-safe `Object.prototype.hasOwnProperty.call(env, key)` or `Object.keys(env)` would silently reject or crash on this fixture. Set up `.loopx/ralph/index.sh` that observes `MYVAR` and `OTHERVAR` via `observe-env`. Drive: `const env = Object.create(null); env.MYVAR = "from-options"; env.OTHERVAR = "second-value"; await runPromise("ralph", { env, maxIterations: 1 });` Assert: (a) the promise resolves (no rejection — null-prototype is a conforming env shape), (b) the script's `MYVAR` marker records `{ "present": true, "value": "from-options" }` and `OTHERVAR` records `{ "present": true, "value": "second-value" }` — both own enumerable string-keyed entries reached the child env, and (c) no warning on stderr about the env shape (the absence of `Object.prototype` is structurally fine). A buggy implementation that rejected null-prototype env via `instanceof Object` would fail (a); an implementation that called `env.hasOwnProperty(...)` to enumerate would throw at snapshot time and fail (a) with a `TypeError`. Together with T-API-61i / T-API-61j (null-prototype `options`), this closes the null-prototype-acceptance gap across both the outer `options` shape and the inner `options.env` shape. *(Spec 9.5)*
+- **T-API-56d**: Symbol-keyed property with a **throwing getter** on `options.env` is ignored — the symbol-keyed slot is not read, so the getter never fires and the throw never surfaces. SPEC 9.5's enumeration rule is "own enumerable **string-keyed** entries only" — symbol-keyed properties (own or otherwise) are excluded by predicate, not by exception-handling. T-API-56a covers the basic symbol-keyed-ignore case (a value getter that returns a string); this test pins down the stronger contract: the getter's **side effects** (including a thrown error) must not surface, because loopx must not reach the symbol-keyed slot during enumeration. A buggy implementation that enumerated `Reflect.ownKeys(env)` (which includes symbols) and then filtered by `typeof key === "string"` after invoking the getter would surface the symbol getter's throw as a snapshot-time error — but per SPEC 9.5 the symbol entry is never read in the first place, so a throw observed on the symbol getter is a contract violation. Drive: `const sym = Symbol("SYM-throw"); const env = { OWN: "own-val" }; Object.defineProperty(env, sym, { enumerable: true, get() { throw new Error("symbol-getter-should-never-fire"); } }); await runPromise("ralph", { env, maxIterations: 1 });` Assert: (a) the promise **resolves** (does not reject — the symbol getter was never invoked), (b) the script observed `OWN` with value `"own-val"` (the string-keyed entry reached the child), (c) stderr contains no error referencing `symbol-getter-should-never-fire` and no snapshot-time error (no observable side effect from the symbol getter — proves the symbol slot was filtered before the getter was reached). T-API-56a covers "symbol-keyed entries are absent from the child env"; this test additionally pins down "symbol-keyed slots are never enumerated, so their getters never fire" via the stronger throwing-getter contract. *(Spec 9.5)*
+- **T-API-56e**: Non-enumerable string-keyed property with a **throwing getter** is ignored — the non-enumerable slot is not read, so the getter never fires. Companion to T-API-56d for the non-enumerable-ignore axis. SPEC 9.5's "own enumerable string-keyed entries only" rule excludes non-enumerable properties by predicate; T-API-56b covers the basic non-enumerable-ignore case (with a value descriptor); this test extends it to the throwing-getter variant, proving the non-enumerable slot is never reached during enumeration. Drive: `const env = { VISIBLE: "visible-val" }; Object.defineProperty(env, "HIDDEN", { enumerable: false, get() { throw new Error("non-enumerable-getter-should-never-fire"); } }); await runPromise("ralph", { env, maxIterations: 1 });` Assert: (a) the promise resolves (the non-enumerable getter was not invoked), (b) the script observed `VISIBLE` with value `"visible-val"` (the enumerable entry reached the child), (c) stderr contains no error referencing `non-enumerable-getter-should-never-fire`. A buggy implementation that called `Object.getOwnPropertyNames(env)` (which includes both enumerable and non-enumerable) and filtered after reading would surface the throw and fail (a). T-API-56b covers "non-enumerable entries are absent from the child env"; this test pins down "non-enumerable slots are never read." *(Spec 9.5)*
+- **T-API-56f**: Inherited property with a **non-string value** on `options.env`'s prototype is ignored — the inherited slot is not read, so its non-string value never triggers shape validation. Companion to T-API-56 for the inherited-ignore axis with a sharper contract. SPEC 9.5's "own enumerable string-keyed entries only" rule excludes inherited properties by predicate; T-API-56 covers the basic inherited-ignore case (with a string value); this test extends it to the **non-string-value** variant, proving the inherited slot is never read — because if it were read, its non-string value would surface as a shape-validation error per T-API-54 (non-string entry value rejected). Construct an env whose prototype has a non-string-valued inherited key alongside an own string-keyed entry: `const proto = { INHERITED_NUMBER: 42 }; const env = Object.create(proto); env.OWN = "own-val"; await runPromise("ralph", { env, maxIterations: 1 });` Assert: (a) the promise resolves (the inherited non-string value never reached the value-shape validator — because the inherited slot was never read), (b) the script observed `OWN` with value `"own-val"` (the own entry reached the child), and `INHERITED_NUMBER` is absent from the child env (the inherited slot is filtered, matching T-API-56's basic absence assertion). A buggy implementation that enumerated via `for ... in` (which walks the prototype chain) and then validated values would surface `INHERITED_NUMBER: 42` to the value validator and reject the env shape, failing (a). T-API-56 covers "inherited slots produce absence in the child"; this test pins down "inherited slots are never even validated for shape, because they are filtered out **before** value validation runs" — a stronger contract that catches buggy enumeration order (validate-then-filter rather than filter-then-validate). *(Spec 9.5)*
+- **T-API-56g**: Class-instance `options.env` is accepted as a valid env shape — own enumerable string-keyed entries declared as class fields reach the spawned script. SPEC 9.5 specifies the env shape as "any non-null, non-array, non-function object whose own enumerable string-keyed entries all have string values" — the contract is structural (any non-plain object qualifies provided it satisfies the predicate), not nominal (the contract does not require `Object.prototype` membership or a literal `{ ... }` constructor). T-API-56c covers the null-prototype variant (no prototype at all); this test covers the inverse non-plain shape — a non-`Object.prototype` instance with a class prototype chain — which exercises the same structural-not-nominal contract from the opposite direction. A buggy implementation that accepted only plain object literals (e.g., `Object.getPrototypeOf(env) === Object.prototype`, `env.constructor === Object`, `env instanceof Object && Object.getPrototypeOf(env) === Object.prototype`, or any other "is plain" check) would silently reject this shape and surface a snapshot-time env-shape error. Set up `.loopx/ralph/index.sh` that observes `MYVAR` via `observe-env`. Drive: `class Env { MYVAR = "from-class"; } await runPromise("ralph", { env: new Env() as any, maxIterations: 1 });` (Class field declarations create own enumerable string-keyed properties on the instance, equivalent to `this.MYVAR = "from-class"` in the constructor — this is the canonical ES2022 class-field semantics, not a property on `Env.prototype`.) Assert: (a) the promise resolves (no rejection — the class-instance shape conforms to SPEC 9.5's structural contract), (b) the script's `MYVAR` marker records `{ "present": true, "value": "from-class" }` (the own enumerable string-keyed class-field entry reached the child env), and (c) no warning on stderr about the env shape (a non-plain prototype is structurally fine; the absence of `Object.prototype` does not invalidate the shape). Together with T-API-56c (null-prototype env on the no-prototype side), this closes the structural-not-nominal env-shape gap across both non-plain-object directions and prevents an "implementation only accepts plain object literals" gap. *(Spec 9.5)*
+- **T-API-56h**: A `Map` passed as `options.env` is **accepted as a valid env shape** but contributes **zero environment variables** to the spawned child — Map entries are stored in the engine-internal `[[MapData]]` slot, not as own enumerable string-keyed properties, and so are filtered out by SPEC 9.5's "own enumerable string-keyed entries" predicate. Companion to T-API-56g for the structural-not-nominal contract: T-API-56g proves that a non-plain object with own string-keyed fields is accepted **and contributes**; this test proves that a non-plain object whose conceptual entries live outside the own-enumerable-string-keyed surface is accepted **but contributes nothing**. The combined coverage prevents an implementation from special-casing `Map` (or any other built-in collection type) into an "auto-enumerate the conceptual entries" code path that would violate SPEC 9.5's strict own-enumerable-string-key predicate. SPEC 9.5 explicitly rejects only `null`, arrays, and functions — `Map` is none of those, so it must be accepted as a shape. Set up `.loopx/ralph/index.sh` that observes `MYVAR` via `observe-env`, ensuring the test driver scrubs `MYVAR` from the inherited environment before spawning loopx so that any observed `MYVAR` value can only come from the `env` option. Drive: `const env = new Map([["MYVAR", "x"]]) as any; await runPromise("ralph", { env, maxIterations: 1 });` Assert: (a) the promise resolves (no rejection — `Map` is a non-null, non-array, non-function object, so the shape is accepted per SPEC 9.5), (b) the script's `MYVAR` marker records `{ "present": false }` — the Map's `[["MYVAR", "x"]]` entry is **not** exposed as an own enumerable string-keyed property on the `Map` object, so SPEC 9.5's predicate filters it out and no `MYVAR` value reaches the child env, and (c) no warning on stderr about the env shape (acceptance is silent — the empty enumeration result is not an error). A buggy implementation that special-cased `Map` and iterated its conceptual entries would surface `MYVAR=x` to the child and fail (b); a buggy implementation that rejected `Map` as an invalid env shape would fail (a). *(Spec 9.5)*
+- **T-API-56i**: `run()`-surface representative coverage of the SPEC 9.5 `RunOptions.env` filtering predicate and structural-shape acceptance — generator-surface parity for the `runPromise()` matrix covered by T-API-56 / T-API-56a / T-API-56b / T-API-56c / T-API-56g / T-API-56h. ADR-0004's `RunOptions.env` decision applies the SPEC 9.5 own-enumerable-string-keyed predicate equally to `run()` and `runPromise()`; the existing positive-filtering tests almost all exercise `runPromise()`, leaving a parity gap on the generator surface. A buggy implementation that wired up the env-snapshot logic correctly on `runPromise()` but used a different code path on `run()` (e.g., a duplicated implementation that walked the prototype chain on the generator surface, or that rejected non-plain objects) would pass the entire T-API-56* `runPromise()` matrix and fail this test. **Parameterize over five variants** corresponding to the five distinct SPEC 9.5 sub-rules covered by the `runPromise()` matrix: variant **(a) inherited keys ignored** (T-API-56 counterpart) — `const proto = { INHERITED: "proto-val" }; const env = Object.create(proto); env.OWN = "own-val";`; variant **(b) symbol-keyed entries ignored** (T-API-56a counterpart) — `const sym = Symbol("SYM"); const env = { OWN: "own-val", [sym]: "sym-val" };`; variant **(c) non-enumerable string-keyed entries ignored** (T-API-56b counterpart) — `const env = {}; Object.defineProperty(env, "HIDDEN", { value: "hidden-val", enumerable: false }); env.VISIBLE = "visible-val";`; variant **(d) null-prototype env accepted with own entries reaching the child** (T-API-56c counterpart) — `const env = Object.create(null); env.MYVAR = "from-options";`; variant **(e) class-instance and `Map` shapes — accepted, with class fields reaching the child and `Map` conceptual entries filtered out** (T-API-56g + T-API-56h counterparts in one variant since both pin SPEC 9.5's structural-not-nominal contract on opposite ends): sub-step (e1) `class Env { MYVAR = "from-class"; } const env = new Env() as any;` — assert `MYVAR` reaches the child as `"from-class"`; sub-step (e2) `const env = new Map([["MYVAR", "x"]]) as any;` (with `MYVAR` scrubbed from the inherited environment first) — assert the promise / generator resolves and `MYVAR` is **absent** from the child env. Set up `.loopx/ralph/index.sh` that observes the relevant variable names (`OWN`, `INHERITED`, `VISIBLE`, `HIDDEN`, `MYVAR`) via `observe-env` and writes a JSON marker per variant. For each variant, drive via `run()`: `const gen = run("ralph", { env, maxIterations: 1 }); for await (const _ of gen) { /* drain */ }` (or, equivalently, `await gen.next()` followed by `await gen.next()` to complete). Assert per-variant: (a) the variant's filtering or acceptance outcome matches the `runPromise()` counterpart's assertion exactly — `INHERITED` absent / `OWN` present (variant a); `OWN` present / no symbol-derived key present (variant b); `VISIBLE` present / `HIDDEN` absent (variant c); `MYVAR` present with value `"from-options"` (variant d); `MYVAR` present with value `"from-class"` (variant e1) and `MYVAR` absent (variant e2), (b) no rejection or option-snapshot error surfaces — the generator settles cleanly via `{ done: true }` after the iteration completes (positive-acceptance assertion), and (c) no warning on stderr about the env shape. Together with T-API-56 / T-API-56a / T-API-56b / T-API-56c / T-API-56g / T-API-56h on the `runPromise()` surface, this closes the surface-parity gap for SPEC 9.5's positive-filtering and structural-shape-acceptance contracts on the generator surface. The throwing-getter / throwing-trap contract-violation variants (T-API-56d / T-API-56e / T-API-56f and the wider T-API-62* / T-API-62h* family) are already covered on the `run()` surface via the broader option-snapshot error path; this test covers only the positive-filtering and positive-acceptance axis. *(Spec 9.5, 9.1)*
+
+##### Runtime-Rejected Names / Values (Embedded NUL)
+
+- **T-API-57**: `RunOptions.env` entry with embedded NUL in the value surfaces as a spawn failure **and `LOOPX_TMPDIR` is cleaned up before rejection**. `runPromise("ralph", { env: { MYVAR: "bad\0val" }, maxIterations: 1 })`. Per SPEC 9.5 "No name validation beyond string-to-string" — runtime-level rejections (embedded NUL) surface at child launch / spawn failure. Per SPEC 7.2 / 7.4 / 9.3, child-launch / spawn failure after tmpdir creation is a normative cleanup trigger and cleanup runs before the promise rejects. **Run under a test-isolated `TMPDIR` parent** (per the section 4.7 suite-wide isolation guidance) so the post-rejection scan is bounded. Assert: (a) the promise rejects with a spawn-failure error — the error is *not* a shape-validation error (shape validation passed; the rejection comes from the runtime's environment-building layer), (b) the workflow script did not run (no marker file from `ralph:index`), and (c) **`LOOPX_TMPDIR` cleanup ran before the promise rejected** — no `loopx-*` directory remains under the test-isolated `TMPDIR` parent (cleanup is normative per SPEC 7.4 "Cleanup triggers" and the ordering is normative per SPEC 9.3 "Cleanup ordering is observable. When `LOOPX_TMPDIR` cleanup runs as part of an error path ... it runs before the generator throws or the promise rejects"). A buggy implementation that surfaced the spawn failure without running cleanup would leave a `loopx-*` directory under the isolated parent and fail (c). *(Spec 7.2, 7.4, 9.3, 9.5)*
+- **T-API-57a**: `RunOptions.env` entry with embedded NUL in the key surfaces as a spawn failure **and `LOOPX_TMPDIR` is cleaned up before rejection**. `runPromise("ralph", { env: { "BAD\0KEY": "val" }, maxIterations: 1 })`. Same SPEC contract as T-API-57 (runtime rejection at spawn, cleanup is normative, ordering is observable). **Run under a test-isolated `TMPDIR` parent** per the section 4.7 suite-wide isolation guidance. Assert: (a) the promise rejects with a spawn-failure error, (b) the workflow script did not run (no marker file), and (c) **no `loopx-*` directory remains under the test-isolated `TMPDIR` parent** — cleanup ran before the promise rejected. NUL-in-key counterpart to T-API-57 (NUL-in-value); both must satisfy the same cleanup contract. *(Spec 7.2, 7.4, 9.3, 9.5)*
+- **T-API-57h**: Generator-surface counterpart to T-API-57 — `run("ralph", { env: { MYVAR: "bad\0val" }, maxIterations: 1 })` throws a spawn failure on first `next()` and `LOOPX_TMPDIR` is cleaned up before the throw. SPEC 9.1 / 9.3 specify that the generator surface uses the same pre-iteration error path as `runPromise()` for spawn failures, and SPEC 7.4's cleanup trigger list ("Child launch / spawn failure after tmpdir creation") is independent of which run surface is in use. T-API-57 covers `runPromise()`; T-API-57f covers the generator under `maxIterations: 0` (no spawn → no spawn failure). This test closes the non-zero-iteration `run()` branch. **Run under a test-isolated `TMPDIR` parent** per the section 4.7 suite-wide isolation guidance. Drive `const g = run("ralph", { env: { MYVAR: "bad\0val" }, maxIterations: 1 }); await g.next();`. Assert: (a) the first `next()` rejects (the generator throws) with a spawn-failure error — not a shape-validation error, (b) the workflow script did not run, and (c) no `loopx-*` directory remains under the test-isolated `TMPDIR` parent — cleanup ran before the throw, mirroring SPEC 9.3's "Cleanup ordering is observable" clause on the generator surface. *(Spec 7.2, 7.4, 9.1, 9.3, 9.5)*
+- **T-API-57i**: Generator-surface counterpart to T-API-57a — `run("ralph", { env: { "BAD\0KEY": "val" }, maxIterations: 1 })` throws a spawn failure on first `next()` and `LOOPX_TMPDIR` is cleaned up before the throw. NUL-in-key counterpart to T-API-57h. **Run under a test-isolated `TMPDIR` parent** per the section 4.7 suite-wide isolation guidance. Assert: (a) the first `next()` rejects with a spawn-failure error, (b) the workflow script did not run, and (c) no `loopx-*` directory remains under the test-isolated `TMPDIR` parent. Together with T-API-57 / T-API-57a (`runPromise()`) and T-API-57h (NUL-in-value, `run()`), this completes the four-way matrix (run surface × NUL-position) for `RunOptions.env` runtime-rejection spawn failures, each pinning down the cleanup-before-error-surface contract. *(Spec 7.2, 7.4, 9.1, 9.3, 9.5)*
+- **T-API-57b**: `RunOptions.env` entry with `=` in the key surfaces per runtime behavior. `runPromise("ralph", { env: { "BAD=KEY": "val" }, maxIterations: 1 })`. Per SPEC 9.5, loopx does not reject `=` in env names at the option-shape level; runtime behavior is not pinned beyond "Runtime-level rejections ... surface as child launch / spawn failures at spawn time." On POSIX, an env entry serialized from a key containing `=` may be rejected by the runtime, or may be accepted with runtime/OS-dependent parsing that does **not** preserve the original key name as observable in `process.env`. Assert only: (a) loopx does **not** reject the env object as an option-shape / shape-validation error (the failure surface is never "invalid `options.env` shape"), and (b) one of two outcomes holds — either the spawn fails as a child launch / spawn failure (the promise rejects with a spawn-failure error per SPEC 7.2 / 9.3), or the child spawns successfully (the promise resolves with one Output). Do **not** assert any specific key/value mapping for `"BAD=KEY"` in the spawn-success branch — the runtime's parsing of the malformed serialized entry is OS- and runtime-dependent and may not preserve `"BAD=KEY"` as a recoverable key name; pinning a specific observable mapping would over-pin behavior SPEC 9.5 deliberately leaves implementation-defined. Documents the "runtime does not distinguish tiers" clause: any env tier (not just `RunOptions.env`) with the same `=`-in-name entry has the same outcome envelope. *(Spec 9.5)*
+- **T-API-57c**: `RunOptions.env` entry with an **empty-string key** is not rejected at the shape level. Per SPEC 9.5 "No name validation beyond string-to-string ... does not reject `=` or empty-string names". Call `runPromise("ralph", { env: { "": "empty-key-value" }, maxIterations: 1 })`. The shape is valid (own enumerable string-keyed property with a string value). Outcome is implementation-defined and runtime-dependent: either (a) the runtime rejects the empty-string key at spawn and the promise rejects with a spawn-failure error (not an option-shape-validation error), or (b) the runtime accepts it and the child env has whatever the runtime does with an empty name (observably absent or present — either is conforming). Assert: the outcome is either (a) or (b) — the CLI exit code / generator outcome is never some third category, and in particular the failure surface is never "invalid `options.env` shape". T-API-57 covers NUL in value, T-API-57a covers NUL in key, T-API-57b covers `=` in key; this test closes the empty-string-key branch, completing shape-level-accepted runtime-rejected coverage. *(Spec 9.5, 9.3)*
+- **T-API-57d**: `runPromise("ralph", { maxIterations: 0, env: { MYVAR: "bad\0val" } })` resolves `[]` rather than rejecting with a spawn failure. SPEC 9.5 / 4.2 / 7.1 specify that `maxIterations: 0` (and CLI `-n 0`) "executes zero iterations" — no child is spawned, and the runtime-rejection paths that surface as spawn failures (NUL in env name or value, etc.) cannot fire because there is no spawn step. SPEC 9.5 "No name validation beyond string-to-string" says shape validation is independent of spawning and surfaces under `maxIterations: 0` just as under any other iteration count, **but NUL in a value is not a shape-validation failure** — it is a runtime-rejection that surfaces only at spawn time. Therefore under `maxIterations: 0` the NUL value silently survives the (skipped) spawn step, and the promise resolves with the empty array per SPEC 9.5's `maxIterations: 0` contract. Assert: (a) the promise resolves (does not reject), (b) the resolved value is `[]` (no Output objects yielded), (c) no spawn-failure error appears on stderr, and (d) no `LOOPX_TMPDIR` was created (consistent with SPEC 7.1 step 6 / SPEC 7.4 — tmpdir is not created under `maxIterations: 0`). This is the zero-iteration counterpart to T-API-57 (which exercises the spawn-failure path at `maxIterations: 1`); it pins down that the spawn-failure path is **gated on the spawn step actually running**, not on the env value being parsed. *(Spec 9.5, 9.2, 7.1, 7.4)*
+- **T-API-57e**: `runPromise("ralph", { maxIterations: 0, env: { "BAD\0KEY": "val" } })` resolves `[]` — NUL in **key** under zero iterations also does not surface as a spawn failure. Same rationale as T-API-57d: the runtime-rejection path requires a spawn step; under `maxIterations: 0` no spawn occurs, so the NUL key survives silently and the promise resolves with `[]`. Assert: (a) resolves, (b) value is `[]`, (c) no spawn-failure error on stderr, (d) no `LOOPX_TMPDIR` created. Together with T-API-57d, this completes zero-iteration coverage for both NUL-in-value and NUL-in-key branches of the runtime-rejection path. *(Spec 9.5, 9.2, 7.1, 7.4)*
+- **T-API-57f**: `run("ralph", { maxIterations: 0, env: { MYVAR: "bad\0val" } })` (the `run()` generator surface, not `runPromise()`) — generator completes immediately on first `next()` with `{ done: true, value: undefined }` and yields no outputs. Same SPEC contract as T-API-57d: under `maxIterations: 0` no spawn occurs, so the NUL value does not surface as a spawn failure on the generator surface either. The generator surface is a separate observation point per SPEC 9.1 vs. 9.2; this test is the `run()` counterpart to T-API-57d. Assert: (a) the first `next()` returns `{ done: true, value: undefined }` (no first yield), (b) no spawn-failure error on stderr, (c) no `LOOPX_TMPDIR` created. *(Spec 9.5, 9.1, 7.1, 7.4)*
+- **T-API-57f2**: `run("ralph", { maxIterations: 0, env: { "BAD\0KEY": "val" } })` — generator completes immediately with `{ done: true, value: undefined }` and yields no outputs. NUL-in-**key** counterpart to T-API-57f (NUL in value) on the `run()` generator surface, completing the zero-iteration matrix: T-API-57d covers `runPromise()` + NUL-in-value, T-API-57e covers `runPromise()` + NUL-in-key, T-API-57f covers `run()` + NUL-in-value, and this test covers the remaining `run()` + NUL-in-key branch. Same SPEC rationale: under `maxIterations: 0` no spawn occurs, so the runtime-rejection path for a NUL-containing name never fires, and the generator completes silently. Assert: (a) first `next()` returns `{ done: true, value: undefined }` (no yield), (b) no spawn-failure error on stderr, (c) no `LOOPX_TMPDIR` created. *(Spec 9.5, 9.1, 7.1, 7.4)*
+- **T-API-57g**: Positive coverage — `RunOptions.env` accepts names that do **not** match the POSIX `[A-Za-z_][A-Za-z0-9_]*` pattern, and those names reach the spawned script. Per SPEC 9.5: "loopx does not enforce the POSIX `[A-Za-z_][A-Za-z0-9_]*` name pattern". Existing T-API-57 / T-API-57a / T-API-57b / T-API-57c cover the runtime-rejection paths (NUL in value, NUL in key, `=` in key, empty-string key) — they prove loopx itself does not enforce POSIX name validation, but they pivot on outcomes that are implementation-defined or surface as errors. None of them assert the **positive case**: a non-POSIX name that the runtime accepts must reach the spawned script unchanged. Without a positive test, an implementation that wrongly applied env-file POSIX-name validation (the SPEC 8.1 env-file key pattern) to `RunOptions.env` would silently drop these names and pass T-API-57 / T-API-57a / T-API-57b / T-API-57c — none of those would catch a missing positive case. Set up `.loopx/ralph/index.ts` containing a TS script that reads `process.env["1BAD"]` and `process.env["FOO-BAR"]` and writes both observed values to a marker file (e.g., JSON-encoded so empty / undefined values are distinguishable from the supplied strings). Call `runPromise("ralph", { env: { "1BAD": "ok-digit-prefix", "FOO-BAR": "ok-dash-interior" }, maxIterations: 1 })`. Assert: (a) the promise resolves (no rejection — these names violate the POSIX pattern but loopx does not validate), (b) the marker file records `process.env["1BAD"] === "ok-digit-prefix"` and `process.env["FOO-BAR"] === "ok-dash-interior"` — both names reached the child env unchanged. The `1BAD` name (digit-first) and `FOO-BAR` name (dash-interior) are the same two violation classes that the env-file key validator (T-SUB-10 digit-first, T-SUB-11b dash-interior) would reject; this test pins down that `RunOptions.env` does **not** apply that validator. **Note on runtime rejection.** Node.js (and Bun) do not reject these names at the spawn / `process.env` level — unlike NUL bytes, non-POSIX names propagate through `child_process.spawn`'s `env` option and appear in the child's `process.env` exactly as supplied. So both observation values are deterministic on the runtimes this suite targets (Node ≥ 20.6, Bun ≥ 1.0). If a future runtime did reject these names, the failure would surface as a spawn-failure error per the "runtime does not distinguish tiers" clause (T-API-57b's outcome shape applies); but on current runtimes the positive assertions hold. *(Spec 9.5)*
+
+##### `LOOPX_*` Keys in `RunOptions.env`
+
+- **T-API-58**: `RunOptions.env` supplying a `LOOPX_*` key is silently overridden by protocol injection (no error, no warning). `runPromise("ralph", { env: { LOOPX_WORKFLOW: "user-fake", CUSTOM: "user-val" }, maxIterations: 1 })`. Script observes both. Assert: `LOOPX_WORKFLOW` shows the real workflow name, `CUSTOM` shows `"user-val"`. Stderr contains no warning about `LOOPX_WORKFLOW` being overridden — loopx does not warn (Spec 9.5). *(Spec 9.5, 8.3)*
+- **T-API-58a**: `RunOptions.env.LOOPX_DELEGATED` reaches spawned scripts (not a script-protocol-protected tier). Per Spec 9.5, `LOOPX_DELEGATED` is startup-reserved only, not script-protocol-protected — `RunOptions.env` may supply it to spawned scripts. Call `runPromise("ralph", { env: { LOOPX_DELEGATED: "user-supplied" } })`. Script observes `LOOPX_DELEGATED`. Assert marker shows `"user-supplied"`. This distinguishes the five script-protocol-protected names (T-API-51a/58) from the startup-only `LOOPX_DELEGATED`. *(Spec 9.5, 3.2, 8.3, 13)*
+
+##### `RunOptions.env` Does Not Affect loopx's Own Lookups
+
+- **T-API-59**: `RunOptions.env` does **not** redirect global env-file lookup. Set `process.env.XDG_CONFIG_HOME=/real/config/path`. Call `runPromise("ralph", { env: { XDG_CONFIG_HOME: "/fake/config/path" }, maxIterations: 1 })`. Script observes `XDG_CONFIG_HOME` — assert marker shows `"/fake/config/path"` (the `RunOptions.env` value reaches the child). But also: place an env file at `/real/config/path/loopx/env` containing `MARKER=real`, and at `/fake/config/path/loopx/env` containing `MARKER=fake`. Script observes `MARKER`. Assert marker shows `"real"` — the global env file was resolved using loopx's own `process.env` (not `RunOptions.env`). Per Spec 8.1 "`RunOptions.env` does **not** affect global env-file path resolution". *(Spec 8.1, 8.3, 9.5)*
+- **T-API-59a**: `RunOptions.env` does **not** redirect global env-file lookup via `HOME`. Similar structure to T-API-59 but using `HOME` instead of `XDG_CONFIG_HOME` (the fallback path). Unset `XDG_CONFIG_HOME`, set `process.env.HOME=/real/home`. Call with `RunOptions.env.HOME=/fake/home`. Place env files at both `/real/home/.config/loopx/env` (`MARKER=real`) and `/fake/home/.config/loopx/env` (`MARKER=fake`). Assert script's `MARKER` observation is `"real"` (loopx read from `$HOME/.config/loopx/env` using loopx's own `HOME`, not the child's). *(Spec 8.1, 8.3, 9.5)*
+- **T-API-59b**: `run()` — `RunOptions.env` does **not** redirect global env-file lookup via `XDG_CONFIG_HOME`. Generator-surface counterpart to T-API-59 (`runPromise()`). The two run surfaces have **different snapshot timing** for inherited `process.env` (lazy under `run()` per SPEC 9.1; eager under `runPromise()` per SPEC 9.2) but both must apply SPEC 8.1's "`RunOptions.env` does **not** affect global env-file path resolution" rule. A buggy implementation that re-read `RunOptions.env` at first `next()` and merged it into the lazy `process.env` snapshot before resolving the global env-file path on the `run()` path — but performed eager resolution correctly under `runPromise()` — would pass T-API-59 but fail this test. **Setup.** Set `process.env.XDG_CONFIG_HOME=/real/config/path`. Place env files at `/real/config/path/loopx/env` containing `MARKER=real`, and at `/fake/config/path/loopx/env` containing `MARKER=fake`. Place `.loopx/ralph/index.sh` (or `.ts`) that observes both `XDG_CONFIG_HOME` and `MARKER` via `observe-env`, then emits `stop:true`. **Drive.** `const gen = run("ralph", { env: { XDG_CONFIG_HOME: "/fake/config/path" }, maxIterations: 1 }); for await (const _ of gen) {}` (or equivalent generator drive pattern). Assert: (a) the marker records `process.env.XDG_CONFIG_HOME === "/fake/config/path"` — the `RunOptions.env` value reaches the child via the SPEC 8.3 tier-2 `RunOptions.env` injection, (b) the marker records `process.env.MARKER === "real"` — the global env file was resolved using loopx's own `XDG_CONFIG_HOME` (the inherited-env value `/real/config/path`), **not** the `RunOptions.env` value, and (c) the generator settled cleanly (no error). Together with T-API-59 (`runPromise()`), this closes the SPEC 8.1 / 9.5 contract on both API surfaces. *(Spec 8.1, 8.3, 9.1, 9.5)*
+- **T-API-59c**: `run()` — `RunOptions.env` does **not** redirect global env-file lookup via `HOME`. Generator-surface counterpart to T-API-59a (`runPromise()`), and the `HOME`-fallback counterpart to T-API-59b (`XDG_CONFIG_HOME`). Same structure as T-API-59b but exercising the `HOME` fallback path: unset `XDG_CONFIG_HOME` from loopx's inherited environment, set `process.env.HOME=/real/home`, place env files at both `/real/home/.config/loopx/env` (`MARKER=real`) and `/fake/home/.config/loopx/env` (`MARKER=fake`). **Drive.** `const gen = run("ralph", { env: { HOME: "/fake/home" }, maxIterations: 1 }); for await (const _ of gen) {}`. Assert: (a) the marker records `process.env.HOME === "/fake/home"` — the `RunOptions.env` value reaches the child, (b) the marker records `process.env.MARKER === "real"` — loopx read from `$HOME/.config/loopx/env` using loopx's own `HOME`, not the child's `HOME` from `RunOptions.env`, and (c) the generator settled cleanly. Together with T-API-59 / T-API-59a / T-API-59b, this closes the `RunOptions.env`-does-not-redirect-global-env-file-path-resolution rule across both surfaces × both fallback variables. *(Spec 8.1, 8.3, 9.1, 9.5)*
+- **T-API-59d**: Local **`envFile`** does **not** redirect global env-file lookup via `XDG_CONFIG_HOME`. SPEC 8.1: "Global env file path resolution (`$XDG_CONFIG_HOME/loopx/env`, with the documented `HOME`-based fallback) reads `XDG_CONFIG_HOME` / `HOME` from the **inherited environment** on the same schedule." Local env-file values (loaded via `-e` / `RunOptions.envFile`) merge into the spawned child's environment **after** loopx has already located and loaded the global env file (per the SPEC 8.3 precedence list and the SPEC 8.1 "inherited environment" wording), so an `XDG_CONFIG_HOME=/fake/config` line in a local env file must not redirect where loopx looks for the global env file. T-API-59 / T-API-59a / T-API-59b / T-API-59c cover this rule on the `RunOptions.env` tier (tier 2 of the SPEC 8.3 precedence list); this test extends the same rule to the local-env-file tier (tier 3). The buggy implementation this test catches: an implementation that built the spawned-child environment first (merging inherited env + global env file + local env file) and *then* re-resolved the global env file using the merged environment would pass T-API-59 (because `RunOptions.env` was correctly excluded from path resolution) and fail this test (because local env file was not). **Setup.** Set `process.env.XDG_CONFIG_HOME=/real/config/path` in the test driver before invoking `runPromise()`. Place a global env file at `/real/config/path/loopx/env` containing `MARKER=real`, and a (decoy) global env file at `/fake/config/path/loopx/env` containing `MARKER=fake`. Place `.loopx/ralph/index.sh` (or `.ts`) that observes both `XDG_CONFIG_HOME` and `MARKER` via `observe-env`, then emits `stop:true`. Place a local env file at `<test-tmp>/local.env` containing `XDG_CONFIG_HOME=/fake/config/path` (the override the script will see, but which must not redirect global env-file path resolution). **Drive.** `await runPromise("ralph", { envFile: "<test-tmp>/local.env", maxIterations: 1 });` **Assert.** (a) the marker records `XDG_CONFIG_HOME === "/fake/config/path"` — the local-env-file value reaches the child via the SPEC 8.3 tier-3 local-env-file injection (overriding the inherited tier-5 value), proving the local env file was loaded and its values reached the spawned script, (b) the marker records `MARKER === "real"` — the global env file was resolved using loopx's own inherited `XDG_CONFIG_HOME` (the inherited tier-5 value `/real/config/path`), **not** the local-env-file value, and (c) the promise resolved (no rejection — neither env file caused a load error). An implementation that resolved the global env file using the merged-with-local-envFile environment would load `/fake/config/path/loopx/env` and the marker would record `MARKER === "fake"`, failing assertion (b). *(Spec 8.1, 8.2, 8.3, 9.5)*
+- **T-API-59e**: Local **`envFile`** does **not** redirect global env-file lookup via `HOME`. `HOME`-fallback counterpart to T-API-59d (`XDG_CONFIG_HOME`). Same structure as T-API-59d but exercises the `$HOME/.config/loopx/env` fallback path: unset `XDG_CONFIG_HOME` from loopx's inherited environment (so the `HOME`-based fallback is exercised), set `process.env.HOME=/real/home`. Place global env files at `/real/home/.config/loopx/env` (`MARKER=real`) and `/fake/home/.config/loopx/env` (`MARKER=fake`). Place a local env file at `<test-tmp>/local.env` containing `HOME=/fake/home` (the override the script will see). The fixture `.loopx/ralph/index.sh` observes both `HOME` and `MARKER`. **Drive.** `await runPromise("ralph", { envFile: "<test-tmp>/local.env", maxIterations: 1 });` **Assert.** (a) the marker records `HOME === "/fake/home"` — the local-env-file value reaches the child, (b) the marker records `MARKER === "real"` — loopx read from `$HOME/.config/loopx/env` using loopx's own inherited `HOME` (`/real/home`), not the local-env-file `HOME`, and (c) the promise resolved. Together with T-API-59d (`XDG_CONFIG_HOME`-direct path), this closes the local-env-file-does-not-redirect-global-env-file-lookup rule across both fallback variables on the `runPromise()` surface; T-API-59h / T-API-59i extend the same rule to the `run()` generator surface (with its lazy pre-iteration timing per SPEC 9.1). *(Spec 8.1, 8.2, 8.3, 9.5)*
+- **T-API-59f**: CLI `-e` file does **not** redirect global env-file lookup via `XDG_CONFIG_HOME` — CLI-surface parity for T-API-59d. SPEC 8.1's "Global env file path resolution ... reads `XDG_CONFIG_HOME` / `HOME` from the **inherited environment** on the same schedule" applies regardless of which surface invokes loopx. T-API-59d covers the rule on the `runPromise()` programmatic surface (with `RunOptions.envFile`); this test covers the same rule on the CLI `-e` surface. The CLI argv-parsing path for `-e` is structurally distinct from the programmatic `RunOptions.envFile` field: a buggy implementation that correctly excluded `RunOptions.envFile` values from global-env-file path resolution but routed CLI `-e` values through a different env-merge code path (e.g., one that fully merged the local file into the to-be-resolved environment before computing the global env-file path) would pass T-API-59d and fail this test. **Setup.** Set `process.env.XDG_CONFIG_HOME=/real/config/path` in the test driver before spawning loopx. Place a global env file at `/real/config/path/loopx/env` containing `MARKER=real`, and a (decoy) global env file at `/fake/config/path/loopx/env` containing `MARKER=fake`. Place `.loopx/ralph/index.sh` that observes both `XDG_CONFIG_HOME` and `MARKER` via `observe-env`, then emits `stop:true`. Place a local env file at `<test-tmp>/local.env` containing `XDG_CONFIG_HOME=/fake/config/path`. **Drive.** `loopx run -e <test-tmp>/local.env -n 1 ralph` via the CLI runner with the inherited environment configured as above. **Assert.** (a) exit code 0, (b) the marker records `XDG_CONFIG_HOME === "/fake/config/path"` — the local-env-file value reaches the child via the SPEC 8.3 tier-3 local-env-file injection (overriding the inherited tier-5 value), proving the local env file was loaded and its values reached the spawned script, and (c) the marker records `MARKER === "real"` — the global env file was resolved using loopx's own inherited `XDG_CONFIG_HOME` (`/real/config/path`), **not** the local-env-file value. An implementation that resolved the global env file using the merged-with-local-`-e` environment would load `/fake/config/path/loopx/env` and the marker would record `MARKER === "fake"`, failing assertion (c). *(Spec 8.1, 8.2, 8.3, 4.2)*
+- **T-API-59g**: CLI `-e` file does **not** redirect global env-file lookup via `HOME` — CLI-surface, `HOME`-fallback parity for T-API-59e. Same structure as T-API-59f but exercises the `$HOME/.config/loopx/env` fallback path: unset `XDG_CONFIG_HOME` from loopx's inherited environment, set `process.env.HOME=/real/home`. Place global env files at `/real/home/.config/loopx/env` (`MARKER=real`) and `/fake/home/.config/loopx/env` (`MARKER=fake`). Place `.loopx/ralph/index.sh` that observes both `HOME` and `MARKER` via `observe-env`. Place a local env file at `<test-tmp>/local.env` containing `HOME=/fake/home`. **Drive.** `loopx run -e <test-tmp>/local.env -n 1 ralph` via the CLI runner with the inherited environment configured as above. **Assert.** (a) exit code 0, (b) the marker records `HOME === "/fake/home"` — the local-env-file value reaches the child via the SPEC 8.3 tier-3 local-env-file injection, and (c) the marker records `MARKER === "real"` — loopx read from `$HOME/.config/loopx/env` using loopx's own inherited `HOME` (`/real/home`), not the local-env-file `HOME`. Together with T-API-59f (`XDG_CONFIG_HOME`-direct path on CLI), this closes the CLI `-e` × {`XDG_CONFIG_HOME`, `HOME`} parity — the previously-open ADR-0004 coverage gap on the CLI surface. T-API-59h / T-API-59i extend the same `envFile` rule to the `run()` generator surface; combined with T-API-59d / T-API-59e (`runPromise()` × `envFile`), T-API-59h / T-API-59i (`run()` × `envFile`), and T-API-59 / T-API-59a / T-API-59b / T-API-59c (`RunOptions.env` tier across both programmatic surfaces × both fallback variables), the SPEC 8.1 "inherited environment" rule is closed across {`RunOptions.env`, `RunOptions.envFile`, CLI `-e`} × {`XDG_CONFIG_HOME`, `HOME`} × all run surfaces. *(Spec 8.1, 8.2, 8.3, 4.2)*
+- **T-API-59h**: `run()` — Local **`envFile`** does **not** redirect global env-file lookup via `XDG_CONFIG_HOME`. Generator-surface counterpart to T-API-59d (`runPromise()`), parallel to how T-API-59b is the generator-surface counterpart to T-API-59. Although SPEC 8.1's "inherited environment" rule itself is independent of snapshot timing, the implementation of envFile-loading + global-env-file-resolution on `run()` exercises **lazy pre-iteration timing** per SPEC 9.1 (inherited `process.env` snapshot taken at first `next()`, not at the call site as on `runPromise()` per SPEC 9.2). A buggy implementation that re-merged the local env file into the lazy-snapshot inherited env before resolving the global env-file path on the `run()` path — but built the spawned-child environment correctly under `runPromise()`'s eager schedule — would pass T-API-59d and fail this test. **Setup.** Set `process.env.XDG_CONFIG_HOME=/real/config/path` in the test driver before invoking `run()`. Place a global env file at `/real/config/path/loopx/env` containing `MARKER=real`, and a (decoy) global env file at `/fake/config/path/loopx/env` containing `MARKER=fake`. Place `.loopx/ralph/index.sh` (or `.ts`) that observes both `XDG_CONFIG_HOME` and `MARKER` via `observe-env`, then emits `stop:true`. Place a local env file at `<test-tmp>/local.env` containing `XDG_CONFIG_HOME=/fake/config/path`. **Drive.** `const gen = run("ralph", { envFile: "<test-tmp>/local.env", maxIterations: 1 }); for await (const _ of gen) {}` (or equivalent generator drive pattern). **Assert.** (a) the marker records `XDG_CONFIG_HOME === "/fake/config/path"` — the local-env-file value reaches the child via the SPEC 8.3 tier-3 local-env-file injection (overriding the inherited tier-5 value), proving the local env file was loaded and its values reached the spawned script, (b) the marker records `MARKER === "real"` — the global env file was resolved using loopx's own inherited `XDG_CONFIG_HOME` (the inherited tier-5 value `/real/config/path`), **not** the local-env-file value, and (c) the generator settled cleanly (no error). An implementation that resolved the global env file using the merged-with-local-envFile environment under the lazy `run()` schedule would load `/fake/config/path/loopx/env` and the marker would record `MARKER === "fake"`, failing assertion (b). *(Spec 8.1, 8.2, 8.3, 9.1, 9.5)*
+- **T-API-59i**: `run()` — Local **`envFile`** does **not** redirect global env-file lookup via `HOME`. Generator-surface counterpart to T-API-59e (`runPromise()`), and the `HOME`-fallback counterpart to T-API-59h (`XDG_CONFIG_HOME`). Same structure as T-API-59h but exercises the `$HOME/.config/loopx/env` fallback path: unset `XDG_CONFIG_HOME` from loopx's inherited environment (so the `HOME`-based fallback is exercised), set `process.env.HOME=/real/home`. Place global env files at `/real/home/.config/loopx/env` (`MARKER=real`) and `/fake/home/.config/loopx/env` (`MARKER=fake`). Place a local env file at `<test-tmp>/local.env` containing `HOME=/fake/home` (the override the script will see). The fixture `.loopx/ralph/index.sh` observes both `HOME` and `MARKER`. **Drive.** `const gen = run("ralph", { envFile: "<test-tmp>/local.env", maxIterations: 1 }); for await (const _ of gen) {}`. **Assert.** (a) the marker records `HOME === "/fake/home"` — the local-env-file value reaches the child, (b) the marker records `MARKER === "real"` — loopx read from `$HOME/.config/loopx/env` using loopx's own inherited `HOME` (`/real/home`), not the local-env-file `HOME`, and (c) the generator settled cleanly. Together with T-API-59h (`run()` × `XDG_CONFIG_HOME`), T-API-59d / T-API-59e (`runPromise()` × `envFile` parity), T-API-59f / T-API-59g (CLI `-e` parity), and T-API-59 / T-API-59a / T-API-59b / T-API-59c (`RunOptions.env` tier across both programmatic surfaces × both fallback variables), this closes the SPEC 8.1 "inherited environment" rule across {`RunOptions.env`, `RunOptions.envFile`, CLI `-e`} × {`XDG_CONFIG_HOME`, `HOME`} × **all** run surfaces (including the `run()` × `envFile` cells, which were the previously-open ADR-0004 coverage gap on the generator surface that this test and T-API-59h close). *(Spec 8.1, 8.2, 8.3, 9.1, 9.5)*
+- **T-API-60**: `RunOptions.env` does **not** redirect tmpdir parent selection. **Per section 4.7's suite-wide test-parent isolation guidance, allocate the inherited-env parent via `const realParent = await fs.mkdtemp(path.join(os.tmpdir(), "loopx-test-real-parent-"))`; do not use a literal `/tmp/real-parent` path (parallel CI workers would collide on the shared path).** The wrong-parent value used in `RunOptions.env` need not exist on disk because loopx must not consult it — pick a unique nonexistent path such as `const fakeParent = path.join(os.tmpdir(), "loopx-test-fake-parent-" + crypto.randomUUID())`. Set `process.env.TMPDIR = realParent`. Call `runPromise("ralph", { env: { TMPDIR: fakeParent }, maxIterations: 1 })`. Script observes both `TMPDIR` and `LOOPX_TMPDIR`. Assert: (a) child's `TMPDIR` equals `fakeParent` (the `RunOptions.env` value reaches the child), (b) `LOOPX_TMPDIR` lives under `realParent` (loopx's own tmpdir parent was captured from loopx's own `process.env`). Restore the original `TMPDIR` value and remove `realParent` at teardown. *(Spec 7.4, 8.3, 9.5)*
+- **T-API-60a**: `run()` — `RunOptions.env` does **not** redirect tmpdir parent selection. Generator-surface counterpart to T-API-60 (`runPromise()`) and T-TMP-29 (which uses `runPromise()` even though it lives in the tmpdir block). The two run surfaces have **different snapshot timing** for inherited env / tmpdir parent (lazy on `run()` per SPEC 9.1 / 7.4; eager on `runPromise()` per SPEC 9.2 / 7.4) but **identical timing** for `RunOptions.env` (eager / call-site capture on both surfaces per SPEC 9.5). A buggy implementation that special-cased the tmpdir-parent / `RunOptions.env` interaction on the lazy-snapshot `run()` surface — perhaps by re-reading `RunOptions.env` at first `next()` and merging it into the lazy `process.env` snapshot before computing `os.tmpdir()` — would pass T-API-60 / T-TMP-29 but fail this test. **Allocate the inherited-env parent via `const realParent = await fs.mkdtemp(path.join(os.tmpdir(), "loopx-test-real-parent-"))`** before invocation per section 4.7's suite-wide test-parent isolation guidance (the literal `/tmp/real-parent` path used in earlier drafts is illustrative only and must not be used in the implementation — parallel CI workers would collide on the shared path; the inherited-env value is the parent loopx's own `os.tmpdir()` selects). The wrong-parent value need not exist on disk because loopx must not consult it; pick a unique nonexistent path such as `const fakeParent = path.join(os.tmpdir(), "loopx-test-fake-parent-" + crypto.randomUUID())`. Set loopx inherited `TMPDIR=realParent`. Drive: `process.env.TMPDIR = realParent; const gen = run("ralph", { env: { TMPDIR: fakeParent }, maxIterations: 1 }); await gen.next();` Fixture `.loopx/ralph/index.sh` observes both `TMPDIR` and `LOOPX_TMPDIR` via `observe-env`, then emits `stop:true`. Assert: (a) child's observed `TMPDIR` equals `fakeParent` (the `RunOptions.env` value reached the child via the SPEC 8.3 tier-2 `RunOptions.env` injection), (b) `LOOPX_TMPDIR` lives under `realParent` (loopx's own tmpdir-parent selection used the lazy inherited-env snapshot of `process.env.TMPDIR` per SPEC 7.4 / 9.1, not the eager `RunOptions.env` capture). Restore the original `TMPDIR` value and remove `realParent` at teardown. Together with T-API-60 (`runPromise()`) and T-TMP-29 / 29b / 29c (parameterized over `TMPDIR` / `TEMP` / `TMP` on `runPromise()`), this closes the `RunOptions.env` × tmpdir-parent contract on both run surfaces. *(Spec 7.4, 8.3, 9.1, 9.5)*
+- **T-API-60b**: `run()` — `RunOptions.env` does **not** redirect tmpdir parent selection via `TEMP`. SPEC 7.4 / 9.5 apply the `RunOptions.env`-does-not-redirect-tmpdir rule symmetrically across `TMPDIR` / `TEMP` / `TMP`. T-API-60a covers `TMPDIR` on the `run()` surface, and T-TMP-29b covers `TEMP` on the `runPromise()` surface; this test parameterizes the `run()` generator surface over `TEMP`. A buggy implementation that special-cased the `TEMP` branch of `os.tmpdir()` resolution on the lazy-snapshot `run()` surface — perhaps by re-reading `RunOptions.env.TEMP` at first `next()` and merging it into the lazy `process.env` snapshot — would pass T-API-60a / T-TMP-29b but fail this test. **Allocate the inherited-env parent via `const rightParent = await fs.mkdtemp(path.join(os.tmpdir(), "loopx-test-right-parent-"))`** before invocation per section 4.7's suite-wide test-parent isolation guidance (literal `/tmp/right-parent` paths in earlier drafts are illustrative only — parallel CI workers would collide on the shared path). Pick a unique nonexistent wrong-parent path such as `const wrongParent = path.join(os.tmpdir(), "loopx-test-wrong-parent-" + crypto.randomUUID())` (need not exist on disk; loopx must not consult it). Configure the driver process's inherited env with `TMPDIR` **unset**, `TMP` **unset**, `TEMP=rightParent`. Drive: `delete process.env.TMPDIR; delete process.env.TMP; process.env.TEMP = rightParent; const gen = run("ralph", { env: { TEMP: wrongParent }, maxIterations: 1 }); await gen.next();` Fixture observes `LOOPX_TMPDIR` and `TEMP` via `observe-env`, then emits `stop:true`. Apply the runtime-aware expected-parent logic from T-TMP-25a: assert `LOOPX_TMPDIR` lives under `rightParent` **iff** the active runtime's `os.tmpdir()` consults `TEMP` in this configuration; otherwise assert the parent matches `os.tmpdir()` evaluated in an identically-configured child process. Always assert the child's observed `TEMP` equals `wrongParent` (the `RunOptions.env` value reached the spawned script's environment per the SPEC 8.3 `RunOptions.env` tier). **Restore original `TMPDIR` / `TEMP` / `TMP` values in a `finally` block and remove `rightParent` at teardown.** *(Spec 7.4, 8.3, 9.1, 9.5)*
+- **T-API-60c**: `run()` — `RunOptions.env` does **not** redirect tmpdir parent selection via `TMP`. Same pattern as T-API-60b for the `TMP` branch: **allocate the inherited-env parent via `const rightParent = await fs.mkdtemp(path.join(os.tmpdir(), "loopx-test-right-parent-"))`** before invocation per section 4.7's suite-wide test-parent isolation guidance (literal `/tmp/right-parent` paths in earlier drafts are illustrative only — parallel CI workers would collide on the shared path). Pick a unique nonexistent wrong-parent path such as `const wrongParent = path.join(os.tmpdir(), "loopx-test-wrong-parent-" + crypto.randomUUID())`. Configure inherited env with `TMPDIR` **unset**, `TEMP` **unset**, `TMP=rightParent`. Drive: `delete process.env.TMPDIR; delete process.env.TEMP; process.env.TMP = rightParent; const gen = run("ralph", { env: { TMP: wrongParent }, maxIterations: 1 }); await gen.next();` Fixture observes `LOOPX_TMPDIR` and `TMP`. Apply the same runtime-aware expected-parent logic (T-TMP-25b). Always assert the child's observed `TMP` equals `wrongParent`. Together with T-API-60a (`run()` × `TMPDIR`), T-API-60b (`run()` × `TEMP`), T-API-60 (`runPromise()` × `TMPDIR`), and T-TMP-29 / 29b / 29c (`runPromise()` × `TMPDIR` / `TEMP` / `TMP`), this closes the `RunOptions.env` × tmpdir-parent contract across both run surfaces × all three variables. **Restore original env values in `finally` and remove `rightParent` at teardown.** *(Spec 7.4, 8.3, 9.1, 9.5)*
+
+#### Advanced `options` / `options.signal` Semantics
+
+Spec 9.1 / 9.3 / 9.5 describe option-snapshot behavior, pre-abort precedence, pinned-priority, pre-first-`next()` carve-out, and other advanced semantics. These tests close coverage.
+
+##### `options` Shape Validation
+
+- **T-API-61**: `run("ralph", null)` → generator throws on first `next()`. Per Spec 9.5, `options` must be omitted, `undefined`, or a non-null non-array non-function object. *(Spec 9.5, 9.1)*
+- **T-API-61a**: `run("ralph", [])` (array) → generator throws on first `next()`. *(Spec 9.5)*
+- **T-API-61b**: `run("ralph", () => {})` (function) → generator throws on first `next()`. *(Spec 9.5)*
+- **T-API-61c**: `run("ralph", "string")` → generator throws on first `next()`. *(Spec 9.5)*
+- **T-API-61d**: `runPromise("ralph", null)` → rejects. *(Spec 9.5, 9.2)*
+- **T-API-61e**: `runPromise("ralph", [])` → rejects. *(Spec 9.5, 9.2)*
+- **T-API-61f**: `run("ralph", undefined)` is equivalent to `run("ralph")` — explicit `undefined` is accepted as "no options supplied". SPEC 9.5 says `options` may be omitted or `undefined`; existing T-API-61 / T-API-61a / T-API-61c / T-API-61e cover the rejected-shape cases, but explicit `undefined` is a conforming value and must be pinned down positively so a buggy implementation cannot silently tighten acceptance to "omitted only". Set up `.loopx/ralph/index.sh` (emits `stop: true`). Drive `run("ralph", undefined)`, iterate to completion. Assert: (a) the generator returns normally (no throw on call or first `next()`), (b) the script executed exactly once (marker file written), and (c) behavior is indistinguishable from `run("ralph")` with `options` omitted — same yield count, same cwd (defaults to `process.cwd()`), same (absent) env-file load. *(Spec 9.5, 9.1)*
+- **T-API-61g**: `runPromise("ralph", undefined)` is equivalent to `runPromise("ralph")`. `runPromise` counterpart to T-API-61f. Drive `await runPromise("ralph", undefined)` on the same fixture. Assert: the promise resolves (does not reject), the resolved array has exactly one Output entry, and behavior matches `runPromise("ralph")` with `options` omitted. *(Spec 9.5, 9.2)*
+- **T-API-61i**: `run("ralph", Object.create(null))` is accepted as a valid options shape — null-prototype objects are conforming. SPEC 9.5 specifies the options shape as "non-null, non-array, non-function object" — the contract is structural ("is it an object that is not specifically excluded"), not nominal ("is it an `instanceof Object` instance with the standard prototype"). A null-prototype object created via `Object.create(null)` is a non-null, non-array, non-function object; it lacks `Object.prototype` (no `hasOwnProperty`, no `toString`, no `__proto__`), but those absences are irrelevant to the SPEC 9.5 contract. T-API-61 / T-API-61a–61c cover the rejected-shape negative cases (null, array, function, string, number); T-API-61f / T-API-61g cover explicit `undefined` as the absent-options case; this test pins down the **null-prototype positive case** so a buggy implementation that uses `instanceof Object` for shape validation (which fails for null-prototype objects since they have no prototype chain to walk to `Object.prototype`) or that calls `options.hasOwnProperty(...)` directly (which throws `TypeError: options.hasOwnProperty is not a function` on null-prototype objects) would be caught. Set up `.loopx/ralph/index.sh` (emits `stop: true`). Drive: `const opts = Object.create(null); opts.maxIterations = 1; opts.cwd = projectDir; const gen = run("ralph", opts);` then iterate to completion. Assert: (a) the generator returns normally (no throw on call or first `next()`), (b) the script executed exactly once (marker file written), and (c) the iteration count, cwd resolution, and absence of env-file load match a corresponding plain-object call (`run("ralph", { maxIterations: 1, cwd: projectDir })`) — the prototype chain difference is invisible to the consumer. A buggy implementation that rejected null-prototype objects via `instanceof Object` would fail (a); an implementation that read options via `hasOwnProperty` without falling back to `Object.prototype.hasOwnProperty.call(opts, key)` would throw at call time and fail (a); an implementation that walked the prototype chain to read field defaults would observe `undefined` for every field and apply the defaults (which is conforming and indistinguishable from absent fields) — the test does not over-pin that detail. *(Spec 9.5, 9.1)*
+- **T-API-61j**: `runPromise("ralph", Object.create(null))` is accepted — null-prototype options are conforming on the `runPromise()` surface. `runPromise()` counterpart to T-API-61i. Same rationale: SPEC 9.5's "non-null, non-array, non-function object" contract holds across both run surfaces, so the null-prototype acceptance must hold on `runPromise()` as well. Drive: `const opts = Object.create(null); opts.maxIterations = 1; const result = await runPromise("ralph", opts);` Assert: (a) the promise resolves (does not reject), (b) the resolved array has exactly one Output entry, and (c) behavior matches the plain-object call. Together with T-API-61i, this completes null-prototype-options coverage on both API surfaces. *(Spec 9.5, 9.2)*
+- **T-API-61k**: Class-instance `options` is accepted as a valid options shape — own enumerable string-keyed class fields define option values. SPEC 9.5: "options must be omitted, `undefined`, or a non-null, non-array, non-function object" — the contract is structural (any non-plain object qualifies provided it satisfies the predicate), not nominal (the contract does not require `Object.prototype` membership or a literal `{ ... }` constructor). T-API-61i / T-API-61j cover the null-prototype variant of the outer `options` shape (no prototype at all); this test covers the inverse non-plain shape — a non-`Object.prototype` instance with a class prototype chain — which exercises the same structural-not-nominal contract from the opposite direction. T-API-56g pins down the same structural-not-nominal contract on the `options.env` axis (class-instance env is accepted); this test is the **outer-options** counterpart, pinning down that an options object with a non-plain prototype chain is accepted on the same terms. A buggy implementation that accepted only plain object literals (e.g., `Object.getPrototypeOf(opts) === Object.prototype`, `opts.constructor === Object`, `opts instanceof Object && Object.getPrototypeOf(opts) === Object.prototype`, or any other "is plain" check) would silently reject this shape and surface a snapshot-time options-shape error. **Setup.** `.loopx/ralph/index.sh` emits `stop: true` (so `maxIterations: 1` and a natural-stop fixture both work). **Drive.** `class Opts { maxIterations = 1; cwd = projectDir; } const result = await runPromise("ralph", new Opts() as any);` (Class field declarations create own enumerable string-keyed properties on the instance, equivalent to `this.maxIterations = 1; this.cwd = projectDir` in the constructor — canonical ES2022 class-field semantics, properties on the **instance**, not on `Opts.prototype`.) Assert: (a) the promise resolves (no rejection — the class-instance shape conforms to SPEC 9.5's structural contract), (b) the resolved array has exactly one Output entry (proving `maxIterations: 1` was read from the instance and applied), (c) the script ran in `projectDir` (proving `cwd` was read from the instance and applied), and (d) no warning on stderr about the options shape. A buggy "plain-object only" check would fail (a) at snapshot time with an options-shape error; a buggy implementation that walked the prototype chain via `for...in` could observe additional inherited keys (e.g., `Opts.prototype.constructor`) and treat them as option values, but since `constructor` is not a recognized option field name, the most likely failure shape is option-fields-resolved-from-instance behavior matching a plain-object call — so the test's load-bearing assertion is the (a)/(b)/(c) structural success case. T-API-61i / T-API-61j cover null-prototype options; together with this test they close the structural-not-nominal options-shape coverage across both non-plain-object directions (no prototype at all, and a class prototype chain). *(Spec 9.5, 9.2)*
+- **T-API-61l**: `Map` passed as `options` is accepted as a valid options shape but contributes **zero option values** (no recognized field names appear as own enumerable string-keyed properties on the `Map` instance). Companion to T-API-61k for the structural-not-nominal contract: T-API-61k proves that a non-plain object with own string-keyed fields is accepted **and contributes**; this test proves that a non-plain object whose conceptual entries live outside the own-enumerable-string-keyed surface is accepted **but contributes nothing**, because Map entries are stored in the engine-internal `[[MapData]]` slot and SPEC 9.5 reads option fields via own enumerable string-keyed property access (consistent with T-API-56h's `options.env`-axis coverage). The combined coverage prevents an implementation from special-casing `Map` (or any other built-in collection type) into an "auto-enumerate the conceptual entries" code path that would violate SPEC 9.5's strict own-enumerable-string-key option-reading semantics. SPEC 9.5 explicitly rejects only `null`, arrays, and functions as options; `Map` is none of those, so it must be accepted as a shape. **Setup.** `.loopx/ralph/index.sh` emits `stop: true` (so the run terminates naturally on first iteration with no `maxIterations` bound from the options). **Drive.** `const opts = new Map([["maxIterations", 1], ["cwd", projectDir]]) as any; const result = await runPromise("ralph", opts);` Assert: (a) the promise resolves (no rejection — `Map` is a non-null, non-array, non-function object, so the shape is accepted per SPEC 9.5), (b) the resolved array has exactly one Output entry (the script ran once and emitted `stop: true` — `maxIterations` from the Map's `[["maxIterations", 1]]` entry did **not** reach the option layer because Map entries are not own enumerable string-keyed properties on the `Map` object; the natural `stop: true` termination is what bounded the run), (c) the child ran in `process.cwd()` (the harness's cwd at call time) — `cwd` from the Map's `[["cwd", projectDir]]` entry did **not** reach the option layer; the default-cwd path applied, (d) no warning on stderr about the options shape (acceptance is silent — the empty enumeration result is not an error). A buggy implementation that special-cased `Map` and iterated its conceptual entries would surface `maxIterations: 1` and `cwd: projectDir` to the option layer and observably differ in (c) (cwd would equal `projectDir` rather than `process.cwd()`); a buggy implementation that rejected `Map` as an invalid options shape would fail (a). Together with T-API-61k (class-instance options accepted **with** field contribution) and T-API-56h (Map as `options.env` accepted with zero contribution), this completes the structural-not-nominal × {field-contribution-required, no-fields-required} coverage matrix across both the outer `options` shape and the inner `options.env` shape. *(Spec 9.5, 9.2)*
+- **T-API-61h**: `runPromise("ralph", { cwd: undefined, envFile: undefined, maxIterations: undefined, signal: undefined, env: undefined })` treats every option field as absent. SPEC 9.5 says each option field, when present and `undefined`, is equivalent to the field being omitted — `cwd` defaults to `process.cwd()`, `envFile` is unused, `maxIterations` has no bound, `signal` captures no signal, `env` contributes no entries. Set up `.loopx/ralph/index.sh` that emits `stop: true` on first iteration (so the run terminates naturally with no `maxIterations` bound). Call `runPromise` with an `options` object whose five pinned fields all explicitly carry `undefined`. Assert: (a) the promise resolves (does not reject) — all five `undefined` values are valid per SPEC 9.5's `T | undefined` field types, (b) the resolved array has exactly one Output entry, (c) the child ran in `process.cwd()` (cwd not redirected), and (d) the spawned environment does not contain any marker-only env key that would only be present if an `env`/`envFile` had been supplied. A buggy shape validator that rejected explicit-`undefined` fields as "not provided but defined" would fail (a); a buggy precedence layer that treated `undefined` as a distinct value and applied null-object semantics in the spawn-environment builder would also fail (c) / (d). Together with T-API-61f / T-API-61g, this pins down explicit-`undefined` acceptance across both API surfaces and all five pinned fields. *(Spec 9.5, 9.2)*
+
+##### Throwing Getters
+
+- **T-API-62**: Throwing getter on `options` object itself — generator throws on first `next()`. `const opts = {}; Object.defineProperty(opts, "env", { get() { throw new Error("boom"); } }); run("ralph", opts);` Generator is returned without throwing at call site; on first `next()`, throws. The error is surfaced as pre-iteration error, not escaping at call site. *(Spec 9.1, 9.5)*
+- **T-API-62a**: Throwing getter on `options.signal` — generator throws on first `next()`. Signal is read first (Spec 9.1), so a throwing `signal` getter captures as a snapshot error. Generator is still returned normally. *(Spec 9.1, 9.5)*
+- **T-API-62b**: Throwing getter on `options.cwd` — generator throws on first `next()`. The `cwd` getter is a pinned-priority option per Spec 9.3 "Pinned pre-iteration priority". *(Spec 9.1, 9.5)*
+- **T-API-62c**: Throwing getter on `options.envFile` — generator throws on first `next()`. Pinned-priority option. *(Spec 9.1, 9.5)*
+- **T-API-62d**: Throwing getter on `options.maxIterations` — generator throws on first `next()`. *(Spec 9.1, 9.5)*
+- **T-API-62e**: Throwing enumerable getter inside `options.env` — generator throws on first `next()`. `const env = { A: "a" }; Object.defineProperty(env, "B", { enumerable: true, get() { throw new Error("boom"); } }); run("ralph", { env })`. *(Spec 9.1, 9.5)*
+- **T-API-62f**: Proxy `ownKeys` trap that throws while enumerating `options.env` — generator throws on first `next()`. *(Spec 9.1, 9.5)*
+- **T-API-62f2** (observational, not a direct conformance pin): Proxy `getOwnPropertyDescriptor` trap behavior while enumerating `options.env`. SPEC 9.5's enumeration of snapshot-time-captured throws explicitly names `Proxy` `ownKeys` traps, throwing enumerable getters, throwing `Proxy` `get` traps on included keys, and throwing `options.env` getters on the options object — but does **not** name the `getOwnPropertyDescriptor` trap. Whether the descriptor trap is invoked during the snapshot depends on enumeration strategy (`Object.keys` invokes it; a `Reflect.ownKeys` + `for ... in`-with-`hasOwnProperty` strategy can avoid it). SPEC explicitly leaves the enumerability-determination strategy implementation-defined ("The strategy used to determine enumerability may invoke descriptor-related proxy traps and remains otherwise implementation-defined"), so SPEC does not pin down a single conforming outcome for a throwing descriptor trap, and this test does not claim direct traceability to any SPEC clause. It is retained as observational coverage to characterize implementation behavior on the descriptor-trap axis without overclaiming a SPEC requirement that does not exist. Construct: `const env = new Proxy({ A: "a" }, { getOwnPropertyDescriptor() { throw new Error("descriptor-trap-boom"); } }); const gen = run("ralph", { env });` Drive `await gen.next()` and observe the outcome. The test passes if **exactly one** of the following holds: (a) the generator threw on first `next()` with the captured trap exception, the error surfaces as an option-snapshot error (not a spawn failure), no child was spawned, and no tmpdir was created — implementation invoked the descriptor trap during the snapshot, captured the throw, and surfaced it via the pre-iteration error path; or (b) the snapshot completed without surfacing the trap throw and the run reached the spawn step normally — implementation did not invoke the descriptor trap during enumeration. The test fails if some third outcome occurs (e.g., the descriptor exception escaped at the call site without being captured, or the run produced a corrupted env and a spawn failure with a misleading message). T-API-62f3 (throwing `get` trap) is the strict-conformance counterpart for the value-read axis: SPEC 9.5 normatively requires ordinary `[[Get]]` semantics for value reads, so a throwing `get` trap on an included key is a SPEC-pinned snapshot-error contract. T-API-62f remains the strict-conformance pin for the `ownKeys` trap. *(Observational; not directly traced to SPEC.)*
+- **T-API-62f3**: Throwing `Proxy` `get` trap on an included `options.env` key is captured and surfaced as a pre-iteration option-snapshot error. SPEC 9.5 normatively specifies ordinary ECMAScript `[[Get]]` semantics for value reads ("After loopx has identified the included own enumerable string-keyed keys, it reads each included key's value using ordinary ECMAScript property `[[Get]]` semantics, equivalent to `env[key]`, exactly once during the call-time snapshot"), and SPEC 9.5's enumeration of snapshot-time-captured throws explicitly names "a throwing `Proxy` `get` trap on an included string key" alongside `ownKeys` / enumerable-getter / outer-`options.env`-getter throws. SPEC 9.1's option-snapshot prose mirrors the enumeration. Construct: `const env = new Proxy({ A: "a", B: "b" }, { ownKeys() { return ["A", "B"]; }, getOwnPropertyDescriptor(t, key) { return { enumerable: true, configurable: true, value: undefined, writable: true }; }, get(t, key) { throw new Error("get-trap-boom"); } }); const gen = run("ralph", { env });` Drive `await expect(gen.next()).rejects.toThrow(/get-trap-boom/);` Assert: (a) the generator throws on first `next()` with the captured trap exception, (b) the error surfaces as an option-snapshot error (not a spawn failure), (c) no child is spawned (no marker file), and (d) no `LOOPX_TMPDIR` was created. A buggy implementation that used descriptor-based extraction (delegating value reads through `Object.getOwnPropertyDescriptor` rather than ordinary `[[Get]]`) would not invoke the `get` trap and would silently reach the spawn step, failing (a). A buggy implementation that let the trap exception escape at the call site would fail SPEC 9.1's "never throws at the call site" rule, observable as a synchronous throw from `run()`. Together with T-API-62f (strict `ownKeys` trap pin) and T-API-62e / T-API-62h10 (entry-getter throws), this closes proxy-trap and entry-throw snapshot-error coverage across the SPEC 9.5-enumerated branches. *(Spec 9.1, 9.5)*
+- **T-API-62g**: Throwing getter under `runPromise` — rejects (not synchronous throw). `runPromise("ralph", new Proxy({}, { get(_, k) { if (k === "env") throw new Error("boom"); return undefined; } }))`. *(Spec 9.2, 9.5)*
+
+##### Option-Field Single-Read Contract
+
+SPEC 9.1 / 9.2 specify: "Each option field is read at most once per call, and a throwing getter or proxy trap is not re-invoked to retry." Existing tests cover many individual throwing-getter / proxy-trap failure cases but do not assert the **single-read** contract itself — a buggy implementation could work for non-throwing getters by reading them multiple times without any test catching the violation.
+
+- **T-API-62h**: `run()` reads each option field at most once per call. Set up counter-based getters on every pinned `RunOptions` field: `signal`, `cwd`, `envFile`, `maxIterations`, `env`. Each getter increments its own counter and returns a **meaningful, used** value: `signal` returns a fresh `new AbortController().signal`, `cwd` returns a real project-root path, `envFile` returns the path to a valid `.env` file, `maxIterations` returns `2`, and `env` returns `{ MYVAR: "value" }` — each is a value the implementation will actually consume when building the spawn environment, loop bound, and so on. Call `run("ralph", opts, ...)` where `opts` has these five counter-based getters. Iterate the generator to completion. After the generator settles, assert each counter is **exactly 1** — no field was read twice during the option snapshot. The exact-one-read assertion is justified only because each getter returns a meaningful non-`undefined` value that the implementation must consume; SPEC 9.1 itself normatively says "each option field is read at most once per call." A buggy implementation that re-reads options across iterations or retries a getter on a caught exception would fail this assertion. An alternative phrasing that matches SPEC's "at most once" wording directly — "no supplied getter is read more than once" — is equally conformant and would pass under implementations that legitimately skip reading a field whose value would be unused; when it is known that every supplied value is consumed (as in this test's fixture), the exact-one-read assertion is the stronger equivalent. *(Spec 9.1, 9.5)*
+- **T-API-62h2**: `runPromise()` reads each option field at most once per call. Same counter-based getter fixture as T-API-62h (each getter returns a meaningful, used value per the T-API-62h rationale), but via `runPromise("ralph", opts)`. Await the promise to resolution. Assert each counter is exactly 1. This is the `runPromise` counterpart to T-API-62h; the same "at most once vs. exactly once" equivalence discussion in T-API-62h applies. *(Spec 9.2, 9.5)*
+- **T-API-62h3**: `run()` does not retry a throwing option-field getter. Per SPEC 9.1 "a throwing getter or proxy trap is not re-invoked to retry" — the single-read contract covers the success path (T-API-62h); this test pins down the throwing path. Set up an `opts` object whose `env` is a throwing counter-getter: `let count = 0; const opts = {}; Object.defineProperty(opts, "env", { get() { count++; throw new Error("env-getter-boom"); } }); const gen = run("ralph", opts); await expect(gen.next()).rejects.toThrow(/env-getter-boom/);` Assert `count === 1` — loopx read the `env` getter once, captured the exception, and did **not** re-invoke the getter during the pre-iteration error surfacing, cleanup, or any other pathway. A buggy implementation that retried the getter in the error-reporting path (e.g., to build a fuller error message) or in a separate cleanup scan would increment the counter past 1. *(Spec 9.1, 9.5)*
+- **T-API-62h4**: `runPromise()` does not retry a throwing option-field getter. Same fixture as T-API-62h3, but via `runPromise("ralph", opts)`. `await expect(runPromise("ralph", opts)).rejects.toThrow(/env-getter-boom/);` Assert `count === 1`. This is the `runPromise()` counterpart to T-API-62h3, proving the no-retry contract holds on both API surfaces. *(Spec 9.2, 9.5)*
+- **T-API-62h5**: `run()` does not retry a throwing `Proxy` `ownKeys` trap inside `options.env`. Per SPEC 9.1, throwing proxy traps are also covered by the no-retry contract. Build a proxy env: `let count = 0; const env = new Proxy({ A: "a" }, { ownKeys() { count++; throw new Error("ownKeys-boom"); } }); const gen = run("ralph", { env });` Iterate and await the first `next()`. Assert: (a) the generator throws with an error referencing the trap failure, and (b) `count === 1`. Proxy-trap counterpart to T-API-62h3; exercises the proxy-enumeration branch of the snapshot codepath rather than the getter branch. *(Spec 9.1, 9.5)*
+- **T-API-62h6**: `runPromise()` does not retry a throwing `Proxy` `ownKeys` trap inside `options.env`. `runPromise()` counterpart to T-API-62h5 — proves the SPEC 9.2 "Identical to `run()` (section 9.1)" / no-retry contract holds on the proxy-enumeration branch under the promise surface, not just the getter branch (which is covered by T-API-62h4). Build the same proxy env: `let count = 0; const env = new Proxy({ A: "a" }, { ownKeys() { count++; throw new Error("ownKeys-boom"); } });` Drive: `await expect(runPromise("ralph", { env })).rejects.toThrow(/ownKeys-boom/);` Assert: (a) the promise rejects with an error referencing the trap failure, and (b) `count === 1` — loopx invoked the proxy `ownKeys` trap once, captured the exception, and did not re-invoke it during the pre-iteration error surfacing, cleanup, or any other pathway. A buggy `runPromise()` implementation that retried the proxy trap during the rejection-construction or aggregate-cleanup paths would increment the counter past 1. Together with T-API-62h3 (`run()` getter no-retry), T-API-62h4 (`runPromise()` getter no-retry), and T-API-62h5 (`run()` proxy-trap no-retry), this completes the no-retry contract coverage across the {`run()` × `runPromise()`} × {throwing getter × throwing proxy `ownKeys` trap} matrix. *(Spec 9.2, 9.5)*
+- **T-API-62h9**: `run()` and `runPromise()` invoke the `Proxy` `get` trap on an included `options.env` key exactly once during the snapshot and do not retry on throw. SPEC 9.5 normatively specifies "`[[Get]]` semantics ... exactly once during the call-time snapshot" for included-key value reads, and SPEC 9.1's no-retry contract ("a throwing getter or proxy trap is not re-invoked to retry") applies to the throwing case. T-API-62h5 / T-API-62h6 cover the no-retry contract for the `ownKeys` trap; this test pins down the same contract for the `get` trap on the value-read axis now that SPEC 9.5 mandates `[[Get]]` semantics. **Parameterize over both run surfaces.** Construct: `let count = 0; const env = new Proxy({ A: "a", B: "b" }, { ownKeys() { return ["A", "B"]; }, getOwnPropertyDescriptor(t, key) { return { enumerable: true, configurable: true, value: undefined, writable: true }; }, get(t, key) { count++; throw new Error("get-trap-boom"); } });` Variant (a) `run()`: `const gen = run("ralph", { env }); await expect(gen.next()).rejects.toThrow(/get-trap-boom/);` Variant (b) `runPromise()`: `await expect(runPromise("ralph", { env })).rejects.toThrow(/get-trap-boom/);` Assert per variant: (a) the generator throws / the promise rejects with an error referencing `get-trap-boom`, and (b) `count === 1` — the implementation invoked the `get` trap, observed the throw on the first included key, captured it, and did not re-invoke during error surfacing or cleanup. A buggy implementation that used descriptor-based extraction (`count === 0`) would fail SPEC 9.5's `[[Get]]`-semantics requirement and (a). A buggy implementation that retried the trap (`count > 1`) would fail SPEC 9.1's no-retry contract. Together with T-API-62h5 / T-API-62h6 (`ownKeys` no-retry) and T-API-62h10 / T-API-62h11 (entry-getter no-retry), this closes the no-retry contract across all SPEC 9.5-enumerated snapshot-throw paths on both run surfaces. *(Spec 9.1, 9.2, 9.5)*
+- **T-API-62h10**: `run()` does not retry a throwing **own enumerable getter on an entry inside `options.env`**. Per SPEC 9.1 / 9.5, the snapshot reads `options.env`'s own enumerable string-keyed entries; an entry implemented as a throwing getter (via `Object.defineProperty`) is one of the snapshot-time-throw paths SPEC 9.5 explicitly enumerates ("a throwing enumerable getter"). T-API-62e covers the *surfacing* of that throw (the generator throws on first `next()`); T-API-62h3 / T-API-62h4 cover the no-retry counter for a throwing **`env` getter on the options object itself**; T-API-62h5 / T-API-62h6 / T-API-62h9 cover the no-retry counter for `Proxy` `ownKeys` / `get` traps inside `options.env`. The remaining branch — the no-retry counter for an own enumerable getter on a **named entry** inside a plain `env` object (the structurally distinct counterpart to T-API-62e's surfacing assertion) — is not pinned down. A buggy implementation that re-invoked the entry getter during error surfacing (e.g., to interpolate the throwing entry's name or value into a fuller error message), during cleanup scanning, or during a defensive "read every entry one more time" pass would increment the counter past 1 without any existing test catching it. **Test-construction note (per the section 1.1 getter / proxy-variant rule):** build the env object directly via `Object.defineProperty` on the same object passed as `options.env` — never via object spread, since spreading invokes the throwing getter in the test harness before `run()` is called. Construct: `let count = 0; const env = { A: "a" }; Object.defineProperty(env, "B", { enumerable: true, get() { count++; throw new Error("env-entry-getter-boom"); } }); const gen = run("ralph", { env }); await expect(gen.next()).rejects.toThrow(/env-entry-getter-boom/);` Assert: (a) the generator throws on first `next()` with the captured exception, (b) the error is an option-snapshot error (not a spawn failure), (c) no child is spawned, (d) no tmpdir is created, and (e) `count === 1` — the entry getter fired once, threw, was captured, and was not re-invoked during error surfacing, cleanup, or any other pathway. The entry-getter no-retry counter is the structurally distinct counterpart to T-API-62h3 (env-on-options-object getter), T-API-62h5 (env-as-proxy-`ownKeys` trap), and T-API-62h9 (env-as-proxy-`get` trap); a bug that affected only the named-entry getter axis (e.g., a per-entry error-message-construction loop that re-read the entry) would slip past those three tests but be caught here. *(Spec 9.1, 9.5)*
+- **T-API-62h11**: `runPromise()` does not retry a throwing own enumerable getter on an entry inside `options.env`. `runPromise()` counterpart to T-API-62h10 — proves the SPEC 9.2 "Identical to `run()` (section 9.1)" / no-retry contract holds for the named-entry getter axis on the promise surface. **Test-construction note** matches T-API-62h10 (use `Object.defineProperty`, never object spread). Construct: `let count = 0; const env = { A: "a" }; Object.defineProperty(env, "B", { enumerable: true, get() { count++; throw new Error("env-entry-getter-boom"); } }); await expect(runPromise("ralph", { env })).rejects.toThrow(/env-entry-getter-boom/);` Assert: (a) the promise rejects with the captured exception, (b) the error is an option-snapshot error (not a spawn failure), (c) no child is spawned, (d) no tmpdir is created, and (e) `count === 1`. Together with T-API-62h10 (`run()` surface), T-API-62h3 / T-API-62h4 (env-on-options-object getter no-retry), T-API-62h5 / T-API-62h6 (env-as-proxy-`ownKeys` trap no-retry), and T-API-62h9 (env-as-proxy-`get` trap no-retry), this completes the no-retry counter coverage for the `options.env` snapshot path across all three structural variants — entry getter, proxy `ownKeys` trap, proxy `get` trap — on both run surfaces. *(Spec 9.2, 9.5)*
+- **T-API-62h7**: `run()` does not retry a throwing `options.signal` getter. Per SPEC 9.1 / 9.5, `signal` is read first in the option-snapshot ordering, and the no-retry contract ("a throwing getter or proxy trap is not re-invoked to retry") applies to every option field — not just `env`. T-API-62h3 / T-API-62h4 cover the no-retry contract for the `env` getter on both surfaces, T-API-62h5 / T-API-62h6 cover the proxy-trap branch, and T-API-62a covers the surfacing of a throwing `signal` getter, but the no-retry counter for the `signal`-getter case specifically is not pinned down. A buggy implementation that retried a throwing `signal` getter — for example to re-attempt listener registration after the first throw — would silently violate the SPEC contract. Construct: `let count = 0; const opts = {}; Object.defineProperty(opts, "signal", { enumerable: true, get() { count++; throw new Error("signal-getter-boom"); } }); const gen = run("ralph", opts); await expect(gen.next()).rejects.toThrow(/signal-getter-boom/);` Assert `count === 1`. This is the `signal`-getter counterpart to T-API-62h3 (env-getter); exercises the **first-read** field's no-retry contract specifically, since `signal` is read before any other field. *(Spec 9.1, 9.5)*
+- **T-API-62h8**: `runPromise()` does not retry a throwing `options.signal` getter. `runPromise()` counterpart to T-API-62h7. Same fixture: `let count = 0; const opts = {}; Object.defineProperty(opts, "signal", { enumerable: true, get() { count++; throw new Error("signal-getter-boom"); } }); await expect(runPromise("ralph", opts)).rejects.toThrow(/signal-getter-boom/);` Assert `count === 1`. Together with T-API-62h7 (run surface), this pins down no-retry for the `signal` getter across both run surfaces, completing the matrix established by T-API-62h3 / T-API-62h4 (env getter) and T-API-62h5 / T-API-62h6 (env proxy trap). *(Spec 9.2, 9.5)*
+- **T-API-62i**: `run()` reads `cwd`, `envFile`, `maxIterations`, and `env` getters synchronously at the call site, before returning the generator. SPEC 9.1 "Option-snapshot timing" says: "`run()` reads its `options` argument at the call site as a synchronous snapshot ... Each option field is read at most once per call." T-API-64k pins down call-site timing for `signal` (via duck-typed `addEventListener` counter); T-API-62h pins down the at-most-once contract across all fields by counting reads after settlement. Neither test directly proves that the **non-signal** getters fire synchronously at the call site rather than lazily on first `next()` — a buggy implementation that deferred all non-signal reads to first `next()` would still pass T-API-62h (counters end at 1) and T-API-64k (signal-only). Construct an `opts` object with **separate counter-based getters** on each non-signal field, each returning a value the implementation will actually consume (so the call-site read is load-bearing — a getter whose return value is `undefined` could be skipped by an implementation that short-circuits on absent values, weakening the "must have been read at call site" claim): `let cwdCount = 0, envFileCount = 0, maxIterCount = 0, envCount = 0; const opts = {}; Object.defineProperty(opts, "cwd", { enumerable: true, get() { cwdCount++; return projectDir; /* a real project directory */ } }); Object.defineProperty(opts, "envFile", { enumerable: true, get() { envFileCount++; return validEnvFilePath; /* a valid .env file path */ } }); Object.defineProperty(opts, "maxIterations", { enumerable: true, get() { maxIterCount++; return 1; } }); Object.defineProperty(opts, "env", { enumerable: true, get() { envCount++; return { MYVAR: "value" }; } });` Each getter returns a meaningful value the implementation must consume to build the spawn environment, resolve cwd, locate the env file, and bound the loop. Drive: `const gen = run("ralph", opts);` and **immediately — without driving `gen.next()`** — assert all four counters are exactly `1`. After the assertion, drive `gen.next()` to drain. Assert: (a) `cwdCount === 1`, `envFileCount === 1`, `maxIterCount === 1`, `envCount === 1` immediately after `run()` returns (synchronous call-site reads of every non-signal field, mirroring the pattern T-API-64k uses for `signal`), (b) after the generator settles, the counters remain at `1` each (no re-reads on iteration; complements T-API-62h's at-most-once assertion at the post-settlement observation point with a stronger pre-`next()` observation point). The exact ordering between non-signal getters is implementation-defined per SPEC 9.1 and is intentionally not asserted; the contract under test is that all four fire **before** `run()` returns. A buggy implementation that deferred non-signal option reads to first `next()` would observe all four counters at `0` immediately after `run()` returned and fail this test. *(Spec 9.1, 9.5)*
+- **T-API-62i2**: `runPromise()` reads `cwd`, `envFile`, `maxIterations`, and `env` getters synchronously at the call site, before returning the promise. SPEC 9.2 "Option-snapshot timing" says: "Identical to `run()` (section 9.1): each option field read at most once, `options.signal` first, throwing getters / traps captured rather than escaping at the call site." T-API-64k2 pins down call-site timing for `signal` on the `runPromise()` surface; this test extends that coverage to the non-signal fields. Use the same counter-based getter fixture as T-API-62i — each getter returns a meaningful value the implementation will consume (`cwd: projectDir`, `envFile: validEnvFilePath`, `maxIterations: 1`, `env: { MYVAR: "value" }`), so the "must have been read at call site" claim is load-bearing rather than satisfied by short-circuiting on `undefined`. Drive: `const p = runPromise("ralph", opts);` and **immediately — without awaiting `p`** — assert all four counters are exactly `1`. After the assertion, `await p` to let the run settle. Assert: (a) all four counters are `1` synchronously after `runPromise()` returns (synchronous call-site reads on the `runPromise()` surface, mirroring T-API-64k2 for `signal`), (b) after the promise settles, the counters remain at `1` each. Together with T-API-62i, this pins down the SPEC 9.1 / 9.2 call-site option-snapshot rule for all non-signal fields across both run surfaces. A buggy `runPromise()` implementation that deferred non-signal option reads to its internal pre-iteration sequence (run after promise creation) would observe all four counters at `0` immediately after `runPromise()` returned and fail this test. *(Spec 9.2, 9.5)*
+- **T-API-62i3**: `run()` — a throwing non-signal option-field getter is invoked exactly once **at the call site** without escaping synchronously, and the captured error is surfaced later via the first `next()`. SPEC 9.1 says: "Any exception raised during the snapshot — a throwing option-field getter, ... — is captured and surfaced via the standard pre-iteration error path on the first `next()`, not at the call site." Existing T-API-62 / T-API-62a–62g cover the "surfaces on first `next()`" behavior, and T-API-62h3 covers the no-retry contract via post-`next()` count. Neither directly proves the **call-site invocation timing** for a throwing non-signal getter — a buggy implementation that deferred the read to first `next()` would still pass T-API-62 (error surfaces) and T-API-62h3 (count is 1 after `next()`). **Parameterize over each non-signal field**: variant (a) `cwd`, variant (b) `envFile`, variant (c) `maxIterations`, variant (d) `env`. For each variant, construct a counter-based throwing getter on the named field and a non-throwing counter on a sibling field for control: `let throwCount = 0; let siblingCount = 0; const opts = {}; Object.defineProperty(opts, "<field>", { enumerable: true, get() { throwCount++; throw new Error("<field>-getter-boom"); } }); Object.defineProperty(opts, "maxIterations", { enumerable: true, get() { siblingCount++; return 1; } });` (skip the sibling getter when `<field>` is `maxIterations`; use `cwd` as the sibling instead). Drive: `const gen = run("ralph", opts);` and **immediately — without driving `gen.next()`** — assert (a) `run()` did **not** throw synchronously at the call site (the call returned a generator, matching SPEC 9.1 "never throws at the call site"), and (b) `throwCount === 1` (the throwing getter was invoked once at call time, captured rather than escaping). Then drive `await expect(gen.next()).rejects.toThrow(/<field>-getter-boom/);` Assert: (c) the captured exception surfaces on first `next()`, and (d) `throwCount === 1` post-`next()` — the captured error was not re-derived by re-invoking the getter (no-retry contract from T-API-62h3 reaffirmed at the call-site-observed timing). The "captured exactly once at call site" combined assertion (b) + (d) is the new surface this test pins down beyond the existing coverage. A buggy implementation that deferred the read to first `next()` would observe `throwCount === 0` immediately after `run()` returned and fail (b). An implementation that re-invoked the getter during error surfacing would fail (d). The order in which non-signal fields are read is implementation-defined per SPEC 9.1, so when the throwing field is read first the sibling counter may end at `0` (sibling read was short-circuited by the early throw) and when the throwing field is read after the sibling, the sibling counter ends at `1`. Both outcomes are conforming; the test does not constrain the sibling counter beyond ensuring the throwing-field counter is exactly `1`. *(Spec 9.1, 9.5)*
+- **T-API-62i4**: `runPromise()` — a throwing non-signal option-field getter is invoked exactly once **at the call site** without escaping synchronously, and the captured error is surfaced later via promise rejection. `runPromise()` counterpart to T-API-62i3. SPEC 9.2 "Option-snapshot timing. Identical to `run()` (section 9.1)" — the same call-site invocation contract holds, and the captured error surfaces via promise rejection rather than first-`next()` throw. **Parameterize over each non-signal field** (same variants as T-API-62i3: `cwd`, `envFile`, `maxIterations`, `env`). Use the same throwing-getter + sibling-counter fixture as T-API-62i3 for each variant. Drive: `const p = runPromise("ralph", opts);` and **immediately — without awaiting `p`** — assert (a) `runPromise()` did **not** throw synchronously at the call site (the call returned a promise, matching SPEC 9.2 "the call itself always returns a promise"), and (b) `throwCount === 1` (the throwing getter was invoked once at call time, captured rather than escaping). Then drive `await expect(p).rejects.toThrow(/<field>-getter-boom/);` Assert: (c) the captured exception surfaces as the promise rejection, and (d) `throwCount === 1` post-rejection — no retry. Same sibling-counter caveat as T-API-62i3 applies (implementation-defined order between non-signal fields means the sibling may or may not have been read before the throw). Together with T-API-62i3, this completes call-site throwing-getter timing coverage for non-signal fields across both run surfaces. *(Spec 9.2, 9.5)*
+
+##### Generator-Returns-Without-Throwing Invariants
+
+- **T-API-63**: `run()` returns a generator without throwing, even under every invalid-options scenario. Parameterize over {invalid-target, invalid-options-shape, throwing-option-getter, already-aborted-signal, invalid-cwd, invalid-envFile, invalid-maxIterations, invalid-env}. For each input, assert that `run(...)` returns a non-null object with `.next()`, `.return()`, `.throw()` methods without raising at the call site. The error is surfaced on first `next()`. This is Spec 9.1's "run() still returns a generator without throwing" invariant — critical because any call-site throw would break consumer composition patterns. *(Spec 9.1)*
+- **T-API-63a**: `runPromise()` returns a promise (not a thrown error) for every invalid input. Parameterize same cases as T-API-63. Assert `runPromise(...)` returns a `Promise` instance (check with `typeof p.then === "function"`) that then rejects. Spec 9.2 — call never throws; failure surfaces as rejection. *(Spec 9.2)*
+
+##### Signal Semantics — Duck-Typed / Reentrant
+
+- **T-API-64**: Invalid `options.signal` shape is an option error, not an abort. `run("ralph", { signal: "not-a-signal" as any })` returns a generator; on first `next()`, throws an option-validation error (not an abort error). The error message references the invalid signal shape. Spec 9.3 — an invalid `options.signal` "remains an ordinary option-snapshot error". *(Spec 9.3, 9.5, 9.1)*
+- **T-API-64a**: Duck-typed signal compatibility. A non-`AbortSignal` object that exposes `aborted: boolean` and `addEventListener("abort", fn)` is accepted as a signal. Create a duck-typed signal `{ aborted: false, addEventListener(type, fn) { if (type === "abort") this._listener = fn; }, _fire() { this.aborted = true; this._listener?.(); } }`. Call `runPromise("ralph", { signal: duck, ... })`, then `duck._fire()`. Assert the promise rejects with the abort error. *(Spec 9.5)*
+- **T-API-64a2**: Duck-typed signal compatibility on the `run()` generator surface — generator-surface counterpart to T-API-64a. SPEC 9.5's `AbortSignal`-compatibility contract applies equally to both run surfaces: a non-`AbortSignal` object exposing `aborted: boolean` and `addEventListener("abort", fn)` as **own** properties must be accepted as a usable signal, and an abort fired through such a signal must surface as an abort error on the generator. T-API-64a covers the own-property duck-signal acceptance contract on `runPromise()`; T-API-64n covers the prototype-inherited variant on both surfaces; but no test directly covers the ordinary own-property duck-signal acceptance on the `run()` surface. A buggy implementation that accepted own-property duck signals on `runPromise()` but used a different validation path on `run()` (e.g., a stricter `instanceof AbortSignal` check on the generator surface) would pass T-API-64a and T-API-64n yet fail this test. Set up `.loopx/ralph/index.sh` as a long-lived fixture: writes `"ready"` to stderr, then sleeps indefinitely (no `output()` / no `loopx output` so the generator is blocked waiting for the first iteration's child to finish). Construct the same own-property duck signal as T-API-64a: `const duck: any = { aborted: false, addEventListener(type: string, fn: () => void) { if (type === "abort") this._listener = fn; }, _fire() { this.aborted = true; this._listener?.(); } };` Drive: `const gen = run("ralph", { signal: duck, maxIterations: 1 }); const nextP = gen.next(); waitForStderr("ready"); duck._fire(); await expect(nextP).rejects.toThrow(/abort/);` Assert: (a) `run()` returns a generator and does not throw at the call site (the duck signal is accepted; the option-snapshot capture succeeds), (b) the script reaches the `"ready"` stderr write before the abort is fired (proves the loop body was entered and the child was active when `_fire()` ran), (c) the generator throws an abort error after `duck._fire()` (the listener registered via the own-property `addEventListener` was invoked, the abort path fired, and the generator surfaces an abort error rather than completing normally), and (d) no option-shape / signal-validation error appears (the duck signal is **accepted** under SPEC 9.5's `AbortSignal`-compatibility contract — the own-property exposure of `aborted` and `addEventListener` is sufficient). Together with T-API-64a (`runPromise()`) and T-API-64n / T-API-64n2 (prototype-inherited on both surfaces), this closes the {own-property / prototype-inherited} × {`run()` / `runPromise()`} duck-signal acceptance matrix. *(Spec 9.5, 9.1)*
+- **T-API-64b**: Reentrant `addEventListener` — duck signal's `addEventListener` synchronously invokes the listener during registration. loopx treats the signal as aborted. Duck signal constructor: `addEventListener(type, fn) { fn(); }`. `runPromise("ralph", { signal: duck, maxIterations: 1 })`. Assert the promise rejects with an abort error on first observation — no child is spawned. Per Spec 9.5, "if `addEventListener` synchronously invokes the registered listener during registration ... loopx treats the signal as aborted". *(Spec 9.5)*
+- **T-API-64c**: Duck-typed signal with `aborted: true` at capture time — loopx treats as aborted, no child spawned. *(Spec 9.5)*
+- **T-API-64d**: Real pre-aborted `AbortSignal`. `const c = new AbortController(); c.abort(); runPromise("ralph", { signal: c.signal, maxIterations: 1 })`. Assert the promise rejects with abort error, no child was spawned. Real `AbortSignal` instances passed already-aborted must always be observed as aborted. *(Spec 9.5)*
+- **T-API-64e**: Signal getter is read first. `const opts = {}; let order = []; Object.defineProperty(opts, "signal", { get() { order.push("signal"); return undefined; } }); Object.defineProperty(opts, "env", { get() { order.push("env"); return undefined; } }); run("ralph", opts);` Await `.next()`. Assert `order[0] === "signal"`. Per Spec 9.1, signal is read before other fields. *(Spec 9.1, 9.5)*
+- **T-API-64f**: Duck-typed signal with a throwing `addEventListener` surfaces as an option-snapshot error, not a call-site throw. Per SPEC 9.5 the `addEventListener` method must be "callable and returns without throwing when loopx invokes it". Construct a duck signal whose `addEventListener` throws synchronously: `const duck = { aborted: false, addEventListener() { throw new Error("listener-register-failed"); } };` Call `run("ralph", { signal: duck, maxIterations: 1 })`. Assert: (a) `run()` returns a generator (not a synchronous throw at the call site), (b) on the first `next()`, the generator throws an option-snapshot error referencing the invalid signal (or wrapping the listener-register exception) — the error must be an **option-shape / signal-validation** error, not an abort error and not a runtime spawn-failure error, (c) no child is spawned, (d) no tmpdir is created. This is the throwing-`addEventListener` counterpart to T-API-64b (reentrant `addEventListener` that fires the listener — treated as aborted) and T-API-64 (non-signal shape — option error). A throwing register does not qualify as aborted (the listener did not actually fire `true` on `aborted`) and does not qualify as a usable signal (the contract is violated), so the correct surface is the option-snapshot error path. *(Spec 9.5, 9.1)*
+- **T-API-64g**: `runPromise()` counterpart to T-API-64f — throwing `addEventListener` on duck signal rejects with an option-snapshot error. Same setup as T-API-64f. `runPromise("ralph", { signal: duck, maxIterations: 1 })`. Assert the promise rejects with an option-shape / signal-validation error (not an abort error, not a spawn-failure error). *(Spec 9.5, 9.2)*
+- **T-API-64h**: Duck-typed signal whose `aborted` getter throws surfaces as an option-snapshot error, not a call-site throw and not an abort. Per SPEC 9.5 the contract requires "a readable `aborted` property" — a getter that throws is not "readable" in the contract sense. Construct `const duck = { addEventListener() {}, get aborted() { throw new Error("aborted-getter-failed"); } };` Call `run("ralph", { signal: duck, maxIterations: 1 })`. Assert: (a) `run()` returns a generator (not a synchronous throw at the call site), (b) on the first `next()`, the generator throws an option-snapshot error referencing the invalid signal (or wrapping the getter exception) — the error must be an **option-shape / signal-validation** error, not an abort error and not a runtime spawn-failure error, (c) no child is spawned, (d) no tmpdir is created. This is the throwing-`aborted`-getter counterpart to T-API-64f (throwing `addEventListener`); both pin down that contract violations during the option-snapshot read surface as option-snapshot errors, not as call-site throws and not as aborts. A throwing `aborted` getter does not qualify as "the signal is aborted" (the implementation cannot read the value `true`) and does not qualify as a usable signal (the contract is violated), so the correct surface is the option-snapshot error path, mirroring T-API-64f's reasoning. *(Spec 9.5, 9.1)*
+- **T-API-64h2**: `runPromise()` counterpart to T-API-64h — throwing `aborted` getter on duck signal rejects with an option-snapshot error. Same `aborted`-throws duck signal as T-API-64h. `runPromise("ralph", { signal: duck, maxIterations: 1 })`. Assert the promise rejects with an option-shape / signal-validation error (not an abort error, not a spawn-failure error). *(Spec 9.5, 9.2)*
+- **T-API-64i**: Duck-typed signal with a non-callable `addEventListener` (e.g., a plain string or number stored on the property name) surfaces as an option-snapshot error. Per SPEC 9.5 the `addEventListener` method must be "callable and returns without throwing when loopx invokes it." A non-callable value violates the "callable" half of the contract. Construct `const duck = { aborted: false, addEventListener: "not-a-function" };` Call `run("ralph", { signal: duck, maxIterations: 1 })`. Assert: (a) `run()` returns a generator (not a synchronous TypeError at the call site), (b) on the first `next()`, the generator throws an option-snapshot error referencing the invalid signal — the error must be an **option-shape / signal-validation** error, not an abort error and not a runtime spawn-failure error, (c) no child is spawned, (d) no tmpdir is created. This is the non-callable-`addEventListener` counterpart to T-API-64f (throws on call) and T-API-64h (throwing `aborted` getter); together the three pin down the three distinct ways a duck-typed signal's `addEventListener` / `aborted` contract can fail (throws on call, throws on read, not callable / not present). The option-snapshot read attempts to invoke `addEventListener`, observes that the property value is not a function, and surfaces the option-shape error rather than calling it (which would otherwise raise a runtime TypeError). *(Spec 9.5, 9.1)*
+- **T-API-64i2**: `runPromise()` counterpart to T-API-64i — non-callable `addEventListener` on duck signal rejects with an option-snapshot error. Same non-callable-`addEventListener` duck signal as T-API-64i. `runPromise("ralph", { signal: duck, maxIterations: 1 })`. Assert the promise rejects with an option-shape / signal-validation error. *(Spec 9.5, 9.2)*
+- **T-API-64i3**: Duck-typed signal whose `addEventListener` property is **missing entirely** (the property does not exist on the object) surfaces as an option-snapshot error. Per SPEC 9.5 the `AbortSignal`-compatibility contract requires "a readable `aborted` property" **and** "an `addEventListener('abort', listener)` method" — both halves must hold. T-API-64i covers the **non-callable-but-present** sub-case (the property exists with a non-function value like a string or number); this test pins down the **missing-property** sub-case (the property does not exist on the object at all), which exercises a slightly different code path in any implementation that distinguishes `prop in obj` / `obj.prop !== undefined` / `typeof obj.prop === "function"` lookups. A buggy implementation that checked only `typeof obj.addEventListener === "function"` for non-callable rejection but special-cased a missing property as "not present, so don't validate" — silently skipping listener registration and letting the run proceed without a usable abort signal — would pass T-API-64i but fail this test. Construct a duck signal with **only** an `aborted` property: `const duck = { aborted: false };` (no own `addEventListener` property; reading `duck.addEventListener` returns `undefined`). Call `run("ralph", { signal: duck, maxIterations: 1 })`. Assert: (a) `run()` returns a generator (not a synchronous TypeError at the call site), (b) on the first `next()`, the generator throws an option-snapshot error referencing the invalid signal — the error must be an **option-shape / signal-validation** error, not an abort error and not a runtime spawn-failure error, (c) no child is spawned, (d) no tmpdir is created. This is the missing-`addEventListener` counterpart to T-API-64i (non-callable but present) and T-API-64f (throws on call); together they cover the three distinct ways the `addEventListener` half of the contract can fail (throws on call, not callable, not present at all). *(Spec 9.5, 9.1)*
+- **T-API-64i4**: `runPromise()` counterpart to T-API-64i3 — missing `addEventListener` property on duck signal rejects with an option-snapshot error. Same `{ aborted: false }` duck signal as T-API-64i3 (no own `addEventListener` property). `runPromise("ralph", { signal: duck, maxIterations: 1 })`. Assert the promise rejects with an option-shape / signal-validation error (not an abort error, not a spawn-failure error). Together with T-API-64f / T-API-64g (throws on call), T-API-64h / T-API-64h2 (throwing `aborted` getter), T-API-64i / T-API-64i2 (non-callable `addEventListener`), and T-API-64j / T-API-64j2 (missing/non-boolean `aborted`), this completes the duck-typed-signal contract-violation coverage across both run surfaces and across all four contract-violation modes (`addEventListener` throws / not callable / not present; `aborted` throws / missing / non-boolean). *(Spec 9.5, 9.2)*
+- **T-API-64j**: Duck-typed signal whose `aborted` property is missing or non-readable / non-boolean is not AbortSignal-compatible and surfaces as an option-snapshot error. Per SPEC 9.5 the contract requires both "a readable `aborted` property" and "an `addEventListener('abort', listener)` method" — both halves must hold, and a missing or non-readable / non-boolean `aborted` value means the object is not AbortSignal-compatible. **Parameterize over each missing/non-boolean variant**: variant (a) **missing own `aborted` property** — `const duck = { addEventListener() {} };` (reading `duck.aborted` returns `undefined`); variant (b) **non-boolean `aborted: undefined` explicitly set** — `const duck = { aborted: undefined as any, addEventListener() {} };`; variant (c) **non-boolean `aborted: "false"` (string)** — `const duck = { aborted: "false" as any, addEventListener() {} };`; variant (d) **non-boolean `aborted: 0` (number)** — `const duck = { aborted: 0 as any, addEventListener() {} };`. For each variant, call `run("ralph", { signal: duck, maxIterations: 1 })`. Assert: (a) `run()` returns a generator (not a synchronous throw at the call site), (b) on the first `next()`, the generator throws an option-snapshot error referencing the invalid signal — the error must be an **option-shape / signal-validation** error, not an abort error (in particular, `aborted === undefined` must not be coerced to "aborted: false" and accepted, because a missing or non-boolean `aborted` is a contract violation distinct from `aborted: false`), and not a spawn-failure error, (c) no child is spawned, (d) no tmpdir is created. This is the missing/non-boolean-`aborted` counterpart to T-API-64f / T-API-64h / T-API-64i; together they cover the contract-violation modes on a duck-typed signal: throwing `addEventListener` (T-API-64f), throwing `aborted` getter (T-API-64h), non-callable `addEventListener` (T-API-64i), and missing-or-non-boolean `aborted` (this test). A buggy implementation that defaulted a missing `aborted` to `false` (or coerced a string/number `aborted` to truthy/falsy) would silently treat the duck signal as a usable signal and proceed, breaking the contract. *(Spec 9.5, 9.1)*
+- **T-API-64j2**: `runPromise()` counterpart to T-API-64j — missing or non-boolean `aborted` on duck signal rejects with an option-snapshot error. Same parameterized variant set (a)–(d) as T-API-64j. For each variant, call `runPromise("ralph", { signal: duck, maxIterations: 1 })`. Assert the promise rejects with an option-shape / signal-validation error. Together with the parallel runPromise tests T-API-64g / T-API-64h2 / T-API-64i2, this completes runPromise parity for the contract-violation modes. *(Spec 9.5, 9.2)*
+- **T-API-64m**: Duck-typed signal whose `addEventListener` **getter** throws on property read surfaces as an option-snapshot error, not a call-site throw and not an abort. Per SPEC 9.5 the `addEventListener` "method must be callable and returns without throwing when loopx invokes it" — but the contract is also violated when the property *read itself* throws, before loopx can ever attempt to invoke the result. T-API-64f covers `addEventListener` that is a **function that throws when called** (the property read returns a function, the call throws); this test covers the structurally different case where the property's **getter** throws on read (loopx never observes any value for `addEventListener` because the read itself raises). The two cases share the same observable contract (option-snapshot error on the first `next()`), but a buggy implementation could plausibly handle one and not the other — for example, an implementation that wrapped the call site (`duck.addEventListener("abort", listener)`) in a try/catch but read the property first as a separate uncaught expression (`const fn = duck.addEventListener; try { fn(...); } catch { ... }`) would let the getter exception escape before the snapshot-capture try/catch had a chance to fire. Construct a duck signal whose `addEventListener` is exposed via a throwing getter: `const duck: any = { aborted: false }; Object.defineProperty(duck, "addEventListener", { enumerable: true, get() { throw new Error("ae-getter-boom"); } });` Call `run("ralph", { signal: duck, maxIterations: 1 })`. Assert: (a) `run()` returns a generator (not a synchronous throw at the call site), (b) on the first `next()`, the generator throws an option-snapshot error referencing the invalid signal (or wrapping the `ae-getter-boom` exception) — the error must be an **option-shape / signal-validation** error, not an abort error and not a runtime spawn-failure error, (c) no child is spawned, (d) no tmpdir is created. **Test-construction note.** The duck signal must use `Object.defineProperty` with a throwing getter, **not** an object literal `{ get addEventListener() { throw ... } }` passed to `run()` directly through any spread / harness path that reads `addEventListener` during construction — because the test harness or the JS engine could otherwise invoke the getter before `run()` is called and surface the exception at the test call site rather than letting loopx capture it via the SPEC 9.5 snapshot path. The `Object.defineProperty` form on a fresh object guards against that hazard. This test is the throwing-`addEventListener`-getter counterpart to T-API-64h (throwing `aborted` getter), T-API-64f (function that throws when called), T-API-64i (non-callable property), and T-API-64i3 (missing property); together they cover the full enumeration of contract-violation modes for the `addEventListener` half — throws-on-call (T-API-64f), throws-on-read (this test), not callable (T-API-64i), not present (T-API-64i3). *(Spec 9.5, 9.1)*
+- **T-API-64m2**: `runPromise()` counterpart to T-API-64m — throwing `addEventListener` getter on duck signal rejects with an option-snapshot error. Same throwing-`addEventListener`-getter duck signal as T-API-64m. `runPromise("ralph", { signal: duck, maxIterations: 1 })`. Assert the promise rejects with an option-shape / signal-validation error (not an abort error, not a spawn-failure error). Together with T-API-64g (function that throws when called), T-API-64h2 (throwing `aborted` getter), T-API-64i2 (non-callable `addEventListener`), and T-API-64i4 (missing `addEventListener`), this completes runPromise parity for the throwing-`addEventListener`-getter contract-violation mode and rounds out the symmetric coverage of all five `addEventListener`-side and `aborted`-side contract-violation modes across both run surfaces. *(Spec 9.5, 9.2)*
+- **T-API-64n**: Duck-typed signal whose `aborted` and `addEventListener` are **inherited from the prototype** (not own properties) is accepted as AbortSignal-compatible — `run()` surface. SPEC 9.5's `AbortSignal`-compatibility contract requires the object to "expose" a readable `aborted` property and a callable `addEventListener('abort', listener)` method, but does **not** require these to be own properties. T-API-64a covers the own-property duck-signal shape (object literal with `aborted` and `addEventListener` as own enumerable properties), and T-API-64d covers the real `AbortSignal` shape (where both halves are inherited from `AbortSignal.prototype`); the **non-`AbortSignal` duck-signal whose halves are inherited from a non-`AbortSignal` prototype** is structurally distinct from both — a buggy implementation that probed for `Object.hasOwn(duck, "aborted")` / `Object.hasOwn(duck, "addEventListener")` instead of using ordinary prototype-walking property access (`duck.aborted` / `duck.addEventListener`) would correctly pass T-API-64a (own properties present) and T-API-64d (real `AbortSignal` is special-cased or instance-checked) yet fail this test, despite SPEC 9.5 explicitly using "expose" rather than "has own". Construct a prototype-bearing duck signal: `class DuckSignal { addEventListener(type, fn) { if (type === "abort") this._listener = fn; } _fire() { this.aborted = true; this._listener?.(); } } DuckSignal.prototype.aborted = false; const duck = new DuckSignal();` — `duck.aborted` and `duck.addEventListener` resolve via the prototype chain (`Object.hasOwn(duck, "aborted") === false` and `Object.hasOwn(duck, "addEventListener") === false` until `_fire()` writes the own property). The instance is **not** an `AbortSignal` (`duck instanceof AbortSignal === false`); it is a plain object with a custom prototype that exposes the contract through inheritance. Call `const c = { abort: () => duck._fire() }; const gen = run("ralph", { signal: duck, maxIterations: 1 });` Drive `gen.next()` to enter the loop body. Once the script writes `"ready"` to stderr (long-lived fixture), call `c.abort()` (which invokes `duck._fire()`, setting `duck.aborted = true` as an own property and synchronously invoking the registered listener). Assert: (a) the generator throws an abort error (the inherited `addEventListener` was successfully invoked at call-time and the listener fired the abort path; SPEC 9.5 "Reading `signal.aborted` must not throw" and "`addEventListener` must expose ... a method that is callable" are both satisfied through prototype lookup), (b) no option-snapshot error / signal-validation error appears (the duck signal is **accepted** under SPEC 9.5's "expose" wording — prototype-inherited halves of the contract are valid), (c) the active child process group was terminated by the abort path (the script's PID is no longer running). The fixture and harness pattern mirror T-API-64a's positive duck-signal acceptance test, with the only structural difference being the prototype-property exposure mode. *(Spec 9.5, 9.1)*
+- **T-API-64n2**: `runPromise()` counterpart to T-API-64n — prototype-inherited `aborted` / `addEventListener` on duck signal is accepted, abort fires correctly. Same prototype-bearing duck signal as T-API-64n. Drive: `const p = runPromise("ralph", { signal: duck, maxIterations: 1 });` Once the script writes `"ready"` to stderr (long-lived fixture), call `duck._fire()` to abort. Assert: (a) the promise rejects with an abort error (not an option-shape / signal-validation error and not a spawn-failure error; the prototype-exposed contract is honored), (b) the active child process group was terminated. Together with T-API-64n (`run()` surface), this closes the prototype-property duck-signal acceptance axis on both run surfaces, mirroring the own-property duck-signal coverage of T-API-64a. A buggy implementation that pinned signal validation to `Object.hasOwn` checks rather than ordinary `[[Get]]` lookups would fail both T-API-64n and T-API-64n2 while passing the rest of the duck-signal suite. *(Spec 9.5, 9.2)*
+
+##### Call-Site Capture Timing
+
+SPEC 9.1 / 9.2 / 9.5 specify that `options.signal` is **read at the call site as a synchronous snapshot** — both run surfaces capture the signal before returning. Existing tests prove the *effects* of various option fields after iteration starts (option-snapshot errors surface lazily on first `next()`, abort errors are throwable, etc.), but they do not directly prove that loopx **registered an abort listener at call time** for a duck-typed signal — distinct from "loopx noticed the signal during pre-iteration". A buggy implementation that deferred all option reads (including `signal.addEventListener`) until first `next()` would still pass the existing abort-during-iteration tests (the listener registration would happen lazily but in time to observe a same-tick abort), but would break the SPEC 9.1 / 9.2 call-site snapshot contract — observable by callers who supply a duck signal whose `addEventListener` increments a counter.
+
+- **T-API-64k**: `run()` registers the `signal.addEventListener('abort', …)` at the call site, not lazily on first `next()`. Construct a duck-typed signal whose `addEventListener` increments an external counter: `let count = 0; const duck = { aborted: false, addEventListener(type, fn) { if (type === "abort") { count++; this._listener = fn; } } };` Call `const gen = run("ralph", { signal: duck, maxIterations: 1 });` and **immediately** — without driving `gen.next()` — assert `count === 1`. The increment must be observable synchronously after `run()` returns, before any consumer interaction with the generator. After the assertion, drive `gen.next()` to drain (clean up resources / let the generator settle). The post-call assertion is the SPEC 9.1 "synchronous snapshot at the call site" surface — a buggy implementation that registered the listener inside the first-`next()` pre-iteration sequence would observe `count === 0` immediately after `run()` returned and fail this test. The duck-typed-signal pathway (rather than a real `AbortSignal`) is required because real `AbortSignal.addEventListener` is not directly observable as a counter without monkeypatching the prototype; the duck signal is the SPEC-blessed compatibility shape (SPEC 9.5 "Duck-typed signal compatibility") and gives a clean observation surface. *(Spec 9.1, 9.5)*
+- **T-API-64k2**: `runPromise()` registers the `signal.addEventListener('abort', …)` at the call site, before `runPromise()` returns. Same duck-typed counter-incrementing signal as T-API-64k. Call `const p = runPromise("ralph", { signal: duck, maxIterations: 1 });` and **immediately** — without awaiting `p` — assert `count === 1`. The increment must be observable synchronously after `runPromise()` returns, before any iteration starts. After the assertion, `await p` to let the run settle (so the test does not leak resources). This is the `runPromise()` counterpart to T-API-64k; together they pin down the SPEC 9.1 / 9.2 call-site snapshot contract for `signal` on both run surfaces. SPEC 9.2 specifies that `runPromise()` snapshot timing is **eager** ("captured synchronously at the `runPromise()` call site"), so the same observation applies. *(Spec 9.2, 9.5)*
+- **T-API-64k3**: `options.signal` is **read** before other option fields. SPEC 9.1 / 9.2 say "`options.signal` is read **before** other `RunOptions` fields, so an already-aborted signal is captured before any other option-field read can produce a snapshot exception." The SPEC ordering rule is on the **field read**, not on full listener-registration completion — pinning the test to listener-registration ordering would over-pin behavior beyond SPEC. **Parameterize the test over both run surfaces — `run()` and `runPromise()`** so each is exercised independently (SPEC 9.1 and SPEC 9.2 both carry the same ordering rule, but the two surfaces share no code path the test can rely on by transitivity, and a buggy implementation could honor the ordering on one surface but not the other). For each surface, construct an `opts` object whose **`signal` is exposed via an enumerable getter** that pushes `"signal"` to an `order` array on read and returns a minimal duck signal, and whose **`env` is exposed via an enumerable getter** that pushes `"env"` to the same `order` array on read: `let order = []; const duckSignal = { aborted: false, addEventListener() {} }; const opts = {}; Object.defineProperty(opts, "signal", { enumerable: true, get() { order.push("signal"); return duckSignal; } }); Object.defineProperty(opts, "env", { enumerable: true, get() { order.push("env"); return undefined; } });` **Variant (a) `run()`**: Call `run("ralph", opts);` and **immediately** — without driving `gen.next()` — assert `order[0] === "signal"` (proving the `signal` getter ran before the `env` getter, regardless of whether `addEventListener` was invoked yet). After the assertion, drive the generator to drain (so the test does not leak resources). **Variant (b) `runPromise()`**: Call `runPromise("ralph", opts);` and **immediately** — without awaiting the promise — assert `order[0] === "signal"`. After the assertion, await the promise to let the run settle. For both variants, do **not** assert that `duckSignal.addEventListener` runs before the `env` getter — SPEC 9.1 / 9.2 require `signal` to be read first but do not require listener registration to complete before subsequent option-field reads. This is the ordering counterpart to T-API-64k / T-API-64k2 — they prove `signal` is read at call time on each surface; this proves it is read **first** on each surface. T-API-64e covers a related ordering observation via throwing-getter sequencing; this test pins the rule down at the option-field-read surface on both surfaces. *(Spec 9.1, 9.2, 9.5)*
+
+##### Abort Precedence
+
+- **T-API-65**: Abort beats missing env-file. `const c = new AbortController(); c.abort(); runPromise("ralph", { signal: c.signal, envFile: "nonexistent.env", maxIterations: 1 })`. Assert promise rejects with abort error (not env-file-missing error). Per Spec 9.3 "Abort precedence over pre-iteration failures", once a usable signal is captured and aborts before the first child spawn, it displaces all other pre-iteration failure modes. *(Spec 9.3, 9.5)*
+- **T-API-65a**: Abort beats invalid target. `const c = new AbortController(); c.abort(); runPromise(":bad", { signal: c.signal, maxIterations: 1 })`. Assert abort error, not invalid-target error. *(Spec 9.3, 9.5)*
+- **T-API-65a2**: Abort beats **non-string target arguments**. SPEC 9.3's abort-precedence rule displaces "target argument / target syntax validation" — the SPEC enumeration covers both target-syntax errors (invalid target strings like `":bad"` covered by T-API-65a) and target-argument errors (non-string `target` per SPEC 9.1: "runtime-invalid `target` values (e.g., `undefined`, `null`, `42`, or any non-string) are rejected lazily"). T-API-65a covers the syntax branch; the **target-argument** branch (non-string) is uncovered. A buggy implementation that routed target-syntax validation through the abort-precedence pathway but rejected non-string targets via a separate eager type-check that escaped the precedence rule would pass T-API-65a yet fail this test. **Parameterize over both surfaces and multiple non-string target values.** Variants: **(i) `target = undefined`**, **(ii) `target = null`**, **(iii) `target = 42`**. For each variant, run two surface variants:
+    - **(promise)**: `const c = new AbortController(); c.abort(); const p = runPromise(<variant> as any, { signal: c.signal, maxIterations: 1 });` Assert: (a) the promise rejects with the **abort** error, **not** the invalid-target / non-string-target error, (b) no child was spawned (no marker file), (c) no `loopx-*` tmpdir was created (assertion scoped to the test-isolated tmpdir parent per the section 4.7 preface).
+    - **(generator)**: `const c = new AbortController(); c.abort(); const gen = run(<variant> as any, { signal: c.signal, maxIterations: 1 }); await expect(gen.next()).rejects.toThrow(/abort/i);` Same three assertions.
+  
+  Together with T-API-65a / T-API-65l (target-syntax branch on both surfaces), this closes both target-argument-validation sub-branches under SPEC 9.3's "target argument / target syntax validation" displacement. *(Spec 9.3, 9.5, 9.1, 9.2)*
+- **T-API-65b**: Abort beats discovery failure (missing `.loopx/`). *(Spec 9.3, 9.5)*
+- **T-API-65c**: Abort beats env-file-load failure (unreadable local env file, mode 000). Create `unreadable.env` at mode 000, pre-abort the signal via `const c = new AbortController(); c.abort(); runPromise("ralph", { signal: c.signal, envFile: "unreadable.env", maxIterations: 1 })`. Assert promise rejects with abort error, not env-file-unreadable error. Per SPEC 8.1 / 8.2, malformed `.env` lines are parser warnings (not fatal), so this test uses an **unreadable** env file — which is a real pre-iteration failure path per SPEC 8.2 / 9.3. T-API-65 covers missing env file (also SPEC 8.2 fatal); this test covers the unreadable-file variant of the same fatal path. **Conditional on `process.getuid() !== 0`.** *(Spec 9.3, 9.5, 8.2)*
+- **T-API-65d**: Abort beats tmpdir-creation failure. Simulate tmpdir-creation failure by setting `TMPDIR` to a path whose parent is read-only. Pre-abort the signal. Assert abort error, not tmpdir-creation error. *(Spec 9.3, 9.5, 7.4)*
+- **T-API-65e**: Invalid `options.signal` shape does not enter the abort pathway. `run("ralph", { signal: "not-a-signal" as any, envFile: "nonexistent.env" })`. Per Spec 9.3 "An invalid `options` value or non-`AbortSignal`-compatible `options.signal` captures no signal and does not enter this pathway". Assert the first-`next()` error references the invalid signal shape (or the missing env file — implementation-defined ordering between those two), **not** an abort error. *(Spec 9.3, 9.5)*
+- **T-API-65v**: `runPromise()` — invalid `options` **wrapper** does not enter the abort pathway, even when the wrapper carries an aborted `AbortSignal`. SPEC 9.3 enumerates two distinct "no usable signal" carve-outs from abort precedence: (i) "An invalid `options` value … captures no signal and does not enter this pathway", and (ii) "non-`AbortSignal`-compatible `options.signal` captures no signal and does not enter this pathway." T-API-65e covers (ii) — the invalid-`signal`-shape branch. The (i) branch — invalid `options` **wrapper** — is currently uncovered at the abort-precedence intersection. Without this case, a buggy implementation could route the invalid-options-wrapper failure through the abort pathway when an aborted signal happens to be attached to the wrapper, even though SPEC 9.3 explicitly forbids it: the invalid options value "captures no signal" before the signal is ever inspected for usability. **Construction.** Build the invalid-options wrapper as an array (one of the SPEC 9.5 "non-conforming values" — arrays are explicitly excluded by the "non-array" clause), then attach an aborted signal as an own property: `const c = new AbortController(); c.abort(); const opts: any = []; opts.signal = c.signal;` then call `runPromise("ralph", opts)`. Assert: (a) the promise rejects with an **invalid-options error** (matching the same error class as T-API-61e — `runPromise()` with an array as `options`) — **not** an abort error, (b) no child was spawned (no marker file), (c) no `loopx-*` tmpdir was created (assertion is scoped to the test-isolated tmpdir parent per the section 4.7 preface). A buggy implementation that read `opts.signal` before validating the wrapper shape, observed the aborted state, and routed through abort precedence would fail (a). *(Spec 9.3, 9.5, 9.2)*
+- **T-API-65w**: `run()` — invalid `options` **wrapper** does not enter the abort pathway, even when the wrapper carries an aborted `AbortSignal`. Generator-surface counterpart to T-API-65v. Same construction (`const c = new AbortController(); c.abort(); const opts: any = []; opts.signal = c.signal;`), then `const gen = run("ralph", opts); await expect(gen.next()).rejects.toThrow(<invalid-options error>);`. Assert: (a) the first `next()` throws an **invalid-options error** (matching the same error class as T-API-61a — `run()` with an array as `options`) — **not** an abort error, (b) no child was spawned, (c) no `loopx-*` tmpdir was created. Together with T-API-65v (`runPromise()`), this closes the SPEC 9.3 "invalid `options` value … captures no signal and does not enter this pathway" carve-out across both API surfaces, complementing T-API-65e (invalid `options.signal` shape, the second SPEC 9.3 carve-out). *(Spec 9.3, 9.5, 9.1)*
+- **T-API-65h**: Abort beats target-resolution failure — missing workflow. Set up `.loopx/ralph/index.sh` (valid), target a workflow that does not exist. `const c = new AbortController(); c.abort(); runPromise("nonexistent-workflow", { signal: c.signal, maxIterations: 1 })`. Assert promise rejects with **abort** error, not missing-workflow error. Per SPEC 9.3 "Abort precedence over pre-iteration failures", target resolution is one of the enumerated pre-iteration failure modes displaced by a pre-aborted signal. T-API-65 covers env-file failure; T-API-65b covers `.loopx/` discovery failure; this test closes the missing-workflow branch of target resolution — a distinct failure category per SPEC 7.1 step 3 that existing abort-precedence tests do not exercise directly. *(Spec 9.3, 9.5, 7.1)*
+- **T-API-65i**: Abort beats target-resolution failure — missing script in existing workflow. Set up `.loopx/ralph/index.sh` (valid, `index` present) but no `check` script. `const c = new AbortController(); c.abort(); runPromise("ralph:check", { signal: c.signal, maxIterations: 1 })`. Assert promise rejects with **abort** error, not missing-script error. This is the missing-script counterpart to T-API-65h (missing workflow) — SPEC 7.1 step 3 enumerates missing workflow and missing script as distinct target-resolution sub-paths, and SPEC 9.3's abort-precedence rule must cover both. *(Spec 9.3, 9.5, 7.1, 4.1)*
+- **T-API-65j**: Abort beats target-resolution failure — missing default entry point (workflow has scripts but no `index`). Set up `.loopx/ralph/check.sh` only (no `index.*`). `const c = new AbortController(); c.abort(); runPromise("ralph", { signal: c.signal, maxIterations: 1 })`. Assert promise rejects with **abort** error, not missing-default-entry-point error. This is the missing-default-entry-point counterpart to T-API-65h (missing workflow) and T-API-65i (missing script under qualified target) — the bare target `"ralph"` resolves to `ralph:index`, which fails with a distinct error path when no `index.*` exists. SPEC 7.1 step 3 enumerates this as the third sub-path of target resolution, and SPEC 9.3's abort-precedence rule covers the whole step. Together T-API-65h/65i/65j pin down abort-precedence across all three target-resolution sub-paths. *(Spec 9.3, 9.5, 7.1, 4.1, 2.1)*
+- **T-API-65k**: `run()` — pre-aborted signal beats missing env-file failure. `const c = new AbortController(); c.abort(); const gen = run("ralph", { signal: c.signal, envFile: "nonexistent.env", maxIterations: 1 });` Assert the first `next()` throws the abort error, not the env-file error. Also assert no child was spawned and no tmpdir was created. This is the generator counterpart to T-API-65. *(Spec 9.3, 9.5, 9.1)*
+- **T-API-65l**: `run()` — pre-aborted signal beats invalid target. `const c = new AbortController(); c.abort(); const gen = run(":bad", { signal: c.signal, maxIterations: 1 });` Assert the first `next()` throws the abort error, not the invalid-target error. This is the generator counterpart to T-API-65a. *(Spec 9.3, 9.5, 9.1)*
+- **T-API-65m**: `run()` — pre-aborted signal beats missing `.loopx/` discovery failure. Create a fixture with no `.loopx/` directory, call `run("ralph", { signal: c.signal, maxIterations: 1 })`, and assert the first `next()` throws the abort error, not the discovery error. This is the generator counterpart to T-API-65b. *(Spec 9.3, 9.5, 9.1)*
+- **T-API-65n**: `run()` — pre-aborted signal beats tmpdir-creation failure. Configure an unwritable tmpdir parent (as in T-TMP-12b), pass a pre-aborted signal, and assert the first `next()` throws the abort error, not the tmpdir-creation error. Also assert no child was spawned and no tmpdir was created. This is the generator counterpart to T-API-65d. *(Spec 9.3, 9.5, 9.1, 7.4)*
+- **T-API-65o**: `run()` — pre-aborted signal beats target-resolution failures. Parameterize over (a) missing workflow, (b) missing script in an existing workflow, and (c) bare workflow target with no `index` script. For each fixture, assert the first `next()` throws the abort error, not the target-resolution error. This is the generator counterpart to T-API-65h / 65i / 65j. *(Spec 9.3, 9.5, 9.1, 7.1)*
+- **T-API-65r**: Pre-aborted signal beats **unreadable global env file** failure on both surfaces. SPEC 9.3's abort-precedence rule explicitly displaces "env-file loading" failures, and SPEC 7.1 step 2 covers both local `-e` and global env files in that loading step. T-API-65 / T-API-65k cover missing **local** env file, T-API-65c covers unreadable **local** env file (mode 000), but the **unreadable global env file** sub-path (the same sub-path as T-TMP-12-global-env-unreadable on the no-abort surface, and as T-SIG-30 on the CLI signal-wins surface) is uncovered on the programmatic abort-precedence surface. Without this case, an implementation could bypass the abort-precedence pathway for the global-env failure mode specifically while still passing the local-env tests. Set up: an isolated `XDG_CONFIG_HOME` with `loopx/env` written and `chmod 000`'d (the same fixture pattern as T-TMP-12-global-env-unreadable; injected into the loopx process's inherited environment, not via `RunOptions.env`, since SPEC 8.1 reads `XDG_CONFIG_HOME` from the inherited environment). A valid `.loopx/ralph/index.sh`. Run two surface variants:
+    - **(r-promise)**: `const c = new AbortController(); c.abort(); const p = runPromise("ralph", { signal: c.signal, maxIterations: 1 });` Assert: (a) the promise rejects with the **abort** error, **not** the global-env-file-read error, (b) no child was spawned, (c) no `loopx-*` tmpdir was created (assertion scoped to the test-isolated tmpdir parent per the section 4.7 preface).
+    - **(r-generator)**: `const c = new AbortController(); c.abort(); const gen = run("ralph", { signal: c.signal, maxIterations: 1 }); await expect(gen.next()).rejects.toThrow(/abort/i);` Same three assertions as the promise variant, but on the generator surface.
+
+  Together with T-SIG-30 (CLI signal-wins over unreadable global env file) and T-TMP-12-global-env-unreadable (no-abort surface), this closes the global-env-unreadable failure mode across all three precedence-relevant surfaces (CLI signal-wins, programmatic abort-precedence, no-abort tmpdir-non-creation). **Conditional on `process.getuid() !== 0`** (root can read mode-000 files). *(Spec 9.3, 9.5, 9.1, 8.1, 7.1)*
+- **T-API-65s**: Pre-aborted signal beats **discovery validation failure** (sibling validation) on both surfaces. SPEC 9.3 says abort-precedence displaces `.loopx/` discovery failures; T-API-65b / T-API-65m cover the **missing-`.loopx/`** sub-path (existence check), but the **sibling-validation** sub-path (SPEC 5.4 fatal validation in run mode — e.g., a sibling workflow with a same-base-name collision or an invalid workflow/script name) is the second SPEC 5.1 / 5.4 discovery-failure path and has its own programmatic-surface coverage at T-TMP-12-programmatic-discovery-validation (no-abort) and T-SIG-25 (CLI signal-wins). The programmatic abort-precedence surface is uncovered. Set up: a valid target workflow `.loopx/ralph/index.sh` alongside a sibling with a fatal validation error (the same fixture used by T-TMP-12-programmatic-discovery-validation — e.g., `.loopx/broken/check.sh` + `.loopx/broken/check.ts` name collision, or `.loopx/-bad-workflow/index.sh` invalid workflow name). Run two surface variants:
+    - **(s-promise)**: `const c = new AbortController(); c.abort(); const p = runPromise("ralph", { signal: c.signal, maxIterations: 1 });` Assert: (a) the promise rejects with the **abort** error, **not** the sibling-validation error, (b) no child was spawned, (c) no `loopx-*` tmpdir was created.
+    - **(s-generator)**: `const c = new AbortController(); c.abort(); const gen = run("ralph", { signal: c.signal, maxIterations: 1 }); await expect(gen.next()).rejects.toThrow(/abort/i);` Same three assertions as the promise variant.
+
+  Together with T-API-65b / T-API-65m (missing-`.loopx/` sub-path, abort-precedence) this closes both SPEC 5.1 / 5.4 discovery-failure sub-paths on the programmatic abort-precedence surface, completing the abort-precedence × discovery × surface matrix that mirrors the CLI signal-wins coverage at T-SIG-24 (missing) and T-SIG-25 (sibling-validation). *(Spec 9.3, 9.5, 9.1, 5.1, 5.4)*
+- **T-API-65t**: Pre-aborted signal beats **invalid workflow / script name** discovery validation failure on both surfaces. Companion to T-API-65s, parameterized specifically over the SPEC 5.3 name-restriction failure path (invalid workflow name like `.loopx/-bad-workflow/index.sh` or invalid script name like `.loopx/broken/-bad.sh`). T-API-65s exercises a same-base-name collision sibling-validation failure; this test exercises the name-restriction sibling-validation failure as a distinct sub-path. The two failure paths share the SPEC 5.4 "fatal in run mode" classification, but the **error class** and the validation code path are distinct (collision vs. name-pattern), and a buggy implementation could route one through the abort-precedence pathway and the other not. Set up: a valid target workflow `.loopx/ralph/index.sh` alongside a sibling with an invalid name (parameterize the test over (a) `.loopx/-bad-workflow/index.sh` invalid workflow name, and (b) `.loopx/broken/-bad.sh` invalid script name). Run both surface variants for each invalid-name fixture (so the test exercises 2 × 2 = 4 sub-cases total): `(t-promise)` analogous to `(s-promise)` and `(t-generator)` analogous to `(s-generator)`. Assert per sub-case: (a) the promise / first `next()` rejects with the **abort** error, **not** the discovery name-restriction error, (b) no child was spawned, (c) no `loopx-*` tmpdir was created. *(Spec 9.3, 9.5, 9.1, 5.1, 5.3, 5.4)*
+- **T-API-65u**: Reentrant duck-signal abort wins over a later pre-iteration failure on the same call. SPEC 9.5 says "if `addEventListener` synchronously invokes the registered listener during registration ... loopx treats the signal as aborted" — the same observable state as a pre-aborted real `AbortSignal`. SPEC 9.3's abort-precedence rule then displaces all other pre-iteration failure modes once a usable signal is captured and aborts. T-API-64b covers the basic reentrant-`addEventListener`-fires-listener case (no other failure to compete with), and T-API-65 / 65a / 65b / 65c / 65d / 65h–65j cover abort-precedence over individual pre-iteration failures using **real** pre-aborted `AbortSignal` instances. The combination — duck signal whose `addEventListener` synchronously fires the listener **plus** a separately-configured later pre-iteration failure on the same call — is uncovered for failure modes that surface during **pre-iteration** (after option-snapshot completes). A buggy implementation that routed real-`AbortSignal` precedence through the abort pathway but treated the synchronously-fired duck-listener case as a separate "synchronously aborted at register time" code path (perhaps surfacing the captured signal-state directly without entering abort-precedence) could pass the existing tests yet surface the later pre-iteration failure here. **Scope of variants — option-snapshot failures excluded.** This test deliberately excludes pairing the reentrant duck signal with a competing **option-snapshot** failure (e.g., a throwing `options.cwd` / `options.envFile` getter, an invalid `options.maxIterations`, an invalid `options.env` shape, or any other field captured at call time). SPEC 9.5 leaves "ordering between reading `aborted` and registering the listener for duck-typed signals" implementation-defined, so an implementation that reads `aborted` first (false), reads the throwing / invalid field next (captured as an option-snapshot error), and never invokes `addEventListener` on the duck (because option-snapshot failed before listener registration was reached) would surface the option-snapshot error without violating SPEC 9.5 — the duck listener was never given the opportunity to fire reentrantly, so the "treats the signal as aborted" precondition was never satisfied. The "abort beats option-snapshot failure" axis is already covered comprehensively for **real** pre-aborted `AbortSignal` instances by T-API-65p / T-API-65q (which enumerate every SPEC 9.5 / 9.1 option-snapshot failure mode); pinning the same axis to a duck-listener trigger would over-pin SPEC 9.5's impl-defined ordering and is intentionally out of scope. The variants below all use failure modes that surface during **pre-iteration** (after option-snapshot completes), where the duck listener has had the opportunity to be registered — and to fire reentrantly — before the pre-iteration failure is detected, making abort precedence observable without depending on intra-snapshot ordering. **Parameterize over both run surfaces and over multiple later-failure variants.** Construct the reentrant duck signal: `const duck = { aborted: false, addEventListener(type, fn) { if (type === "abort") { this.aborted = true; fn(); } } };` Pair it with a later-pre-iteration failure on the same call. Variants: **(i) missing local env file** — `runPromise("ralph", { signal: duck, envFile: "nonexistent.env", maxIterations: 1 })`; **(ii) target-resolution failure** — fixture has `.loopx/other/index.sh`; call with target `"ralph"` (missing workflow). Drive each variant on each surface:
+    - **(promise)**: `await expect(runPromise(<target>, opts)).rejects.toThrow(/abort/i);`
+    - **(generator)**: `const gen = run(<target>, opts); await expect(gen.next()).rejects.toThrow(/abort/i);`
+  
+  Assert per variant per surface: (a) the surfaced rejection / throw is the **abort** error, **not** the configured later pre-iteration failure (env-file-missing or missing-workflow), (b) no child was spawned, (c) no `loopx-*` tmpdir was created (assertion scoped to the test-isolated tmpdir parent per the section 4.7 preface). A buggy implementation that surfaced the later pre-iteration failure despite the reentrant duck listener having already transitioned the signal to aborted would fail (a). Together with T-API-64b (reentrancy in isolation), T-API-65 / 65a / 65b / 65c / 65d / 65h–65j (real-`AbortSignal` precedence), T-API-65p / T-API-65q (real-pre-aborted-signal precedence × the full enumerated option-snapshot failure set), and T-API-65k–65t (precedence × additional pre-iteration failure modes), this closes the SPEC 9.5 reentrant-duck-signal × SPEC 9.3 abort-precedence intersection on the pre-iteration axis. *(Spec 9.3, 9.5, 9.1, 9.2)*
+- **T-API-65p**: `runPromise()` — pre-aborted signal beats **the full enumerated invalid `maxIterations` set plus a representative selection of remaining option-snapshot failures**. SPEC 9.3 "Abort precedence over pre-iteration failures": "Once a usable `AbortSignal` has been captured (a real `AbortSignal` or a duck-typed signal that satisfies the section 9.5 contract), an already-aborted signal at call time, or a signal that aborts during pre-iteration before the first child spawn, displaces all other pre-iteration failure modes on the same call: captured option-snapshot errors, target argument / target syntax validation, `.loopx/` discovery, env-file loading, target resolution, and tmpdir creation." T-API-65g covers a single option-snapshot variant (throwing later-option getter on `env`); T-API-65–65d / 65h–65j cover the non-option-snapshot failure modes (env-file, invalid-target, discovery, env-file-unreadable, tmpdir, target-resolution sub-paths). This test extends the option-snapshot category by parameterizing **exhaustively** over every invalid `maxIterations` value treated as invalid elsewhere in TEST-SPEC.md (so the abort-precedence × `maxIterations` matrix is a strict superset of the validation matrix in T-API-22 etc.) and **representatively** over the remaining option-snapshot families (invalid `cwd` / `envFile` types, throwing getters, invalid `env` shape and entry value, throwing `env` entry getter, throwing `env` proxy `ownKeys` trap, throwing `env` proxy `get` trap on an included key, throwing `options.maxIterations` getter). The full invalid `env` shape/value matrix (every shape from T-API-53–53d and every entry-value variant from T-API-54–54c) is intentionally **not** exhaustively re-parameterized here — those validation paths converge on a single "captured option-snapshot error" code path that the abort-precedence pathway must displace, and the representative sample is sufficient to detect a buggy implementation that bypassed abort-precedence on the option-snapshot category. The cost-benefit favors the broader coverage that lighter env sampling allows in the matrix; tests at the env-shape-validation surface (T-API-53–55, T-API-55a–55d) carry the exhaustive env-shape coverage without abort-precedence pinning. **Invalid `options.signal` is excluded** per SPEC 9.3 "An invalid `options` value or non-`AbortSignal`-compatible `options.signal` captures no signal and does not enter this pathway"; that case is covered separately by T-API-65e and is **not** an abort-precedence path. **Parameterize over each variant.** Drive each variant by constructing options so the variant's invalid value is preserved on the final options object. **Construction rule**: build the **final options object directly** — for plain-data variants, `const opts: any = { signal: c.signal, maxIterations: 1, ...<variant-specific-data-fields> }` is fine; for **getter / proxy variants** (viii, x, xiii, xiv, xv, xvi), the throwing accessor or proxy must be installed directly on `opts` (or on the env object referenced by `opts.env`) using `Object.defineProperty` or by constructing `opts` field-by-field — **never via `{ ...opts, ... }`**, because spreading invokes enumerable getters, proxy `ownKeys` traps, and proxy `get` traps in the test harness before `runPromise()` is called, which surfaces the exception at the test call site rather than letting loopx capture it via the SPEC 9.5 snapshot path (see "Test-construction sanity for getter/proxy variants" in section 1.3). For variants (i)–(vi), the `maxIterations` default of `1` may be replaced by the variant value or omitted entirely so the variant's value is the only one set. Then: `const c = new AbortController(); c.abort(); const p = runPromise("ralph", opts);` Assert per variant: (a) the promise rejects with the **abort** error — not the configured option-snapshot error, (b) no child was spawned (no marker file), (c) no `loopx-*` tmpdir was created (assertion is scoped to the test-isolated tmpdir parent per the section 4.7 preface). **Variants:** **(i) invalid `maxIterations: -1`** (the variant must be the effective `maxIterations`, not overwritten by the default); **(ii) invalid `maxIterations: 1.5`** (same); **(iii) invalid `maxIterations: NaN`** (same); **(iv) invalid `maxIterations: Infinity`** (same — non-finite positive infinity, treated as invalid alongside `NaN` per the SPEC 9.5 finiteness requirement); **(v) invalid `maxIterations: null as any`** (same — `null` is not a finite non-negative integer); **(vi) invalid `maxIterations: "1" as any`** (same — string values are rejected at the type-shape gate, distinct from the numeric-range gates exercised by (i)–(v); pins down that abort-precedence displaces the type-validation failure mode in addition to the value-validation failure modes); **(vii) non-string `cwd: 42 as any`**; **(viii) throwing `cwd` getter** — construct: `const opts: any = { signal: c.signal, maxIterations: 1 }; Object.defineProperty(opts, "cwd", { enumerable: true, get() { throw new Error("cwd-getter-boom"); } });` and call `runPromise("ralph", opts)`; **(ix) non-string `envFile: 42 as any`**; **(x) throwing `envFile` getter** — analogous to (viii): `const opts: any = { signal: c.signal, maxIterations: 1 }; Object.defineProperty(opts, "envFile", { enumerable: true, get() { throw new Error("envFile-getter-boom"); } });`; **(xi) representative invalid `env` shape — `env: [] as any`** (representative sample of the SPEC 9.5 / T-API-53–53d shape-validation matrix; other invalid shapes — `null`, function, string, number — share the same code path); **(xii) representative non-string env entry value — `env: { KEY: 42 as any }`** (representative sample of the SPEC 9.5 / T-API-54–54c entry-value-validation matrix; other invalid entry values — `undefined`, `null`, object, function — share the same code path); **(xiii) throwing enumerable getter inside `env`** — `const env: any = {}; Object.defineProperty(env, "KEY", { enumerable: true, get() { throw new Error("env-entry-getter-boom"); } }); const opts: any = { signal: c.signal, maxIterations: 1, env };` (the `env` value is a plain object whose entry getter throws — assigning it as `opts.env = env` is safe because reading `opts.env` reads the plain reference, not a getter); **(xiv) throwing `env` proxy `ownKeys` trap** — `const env: any = new Proxy({}, { ownKeys() { throw new Error("ownKeys-trap-boom"); } }); const opts: any = { signal: c.signal, maxIterations: 1, env };` (same rationale: the proxy is the value of `opts.env`, not a getter on `opts`, so reading `opts.env` does not trigger the trap; the trap fires only when loopx enumerates the proxy's own keys during snapshot); **(xv) throwing `Proxy` `get` trap on an included `env` key** — `const env: any = new Proxy({ KEY: "value" }, { ownKeys() { return ["KEY"]; }, getOwnPropertyDescriptor() { return { enumerable: true, configurable: true }; }, get() { throw new Error("get-trap-boom"); } }); const opts: any = { signal: c.signal, maxIterations: 1, env };` (the proxy is the value of `opts.env`, not a getter on `opts`, so reading `opts.env` does not trigger any trap during construction; SPEC 9.5 normatively specifies ordinary `[[Get]]` semantics for value reads on included keys, so the throwing `get` trap fires inside loopx's snapshot pass when it reads `env[key]` — T-API-62f3 / T-API-62h9 already pin the snapshot-error surface for this trap under non-aborted runs, and this variant pins the abort-precedence override of that same surface, matching the SPEC 9.5 "throwing `Proxy` `get` trap on an included string key" enumeration); **(xvi) throwing `options.maxIterations` getter** — `const opts: any = { signal: c.signal }; Object.defineProperty(opts, "maxIterations", { enumerable: true, get() { throw new Error("maxIterations-getter-boom"); } });` (the throwing accessor is installed directly on `opts` rather than via spread; SPEC 9.1 / 9.5 specify that `options.maxIterations` is read at most once during the call-time snapshot and a throwing getter is captured as a snapshot exception per the no-retry contract pinned by T-API-62i3 / T-API-62i4; this variant pins down that abort-precedence displaces the captured snapshot error on the `maxIterations` getter axis, structurally distinct from variants (i)–(vi) which exercise the value-validation gate after a non-throwing read returns an invalid value). The "abort wins" outcome must hold across all sixteen variants. **Test-construction sanity check**: before invoking `runPromise`, the test should assert (e.g., for variants (i)–(vi)) that `opts.maxIterations` is the variant value (`-1`, `1.5`, `NaN`, `Infinity`, `null`, or `"1"`), not the default `1` — proving the construction order actually exposes the invalid value. **For getter / proxy variants (viii), (x), (xiii), (xiv), (xv), (xvi)**: the test must additionally guard against accidental harness-side invocation by reading the relevant accessor / trap **never** during construction; constructing `opts` field-by-field (rather than via spread or initializer literals that include `...opts`) is sufficient. A buggy implementation that read any of these option fields before snapshotting `options.signal`, or that surfaced the captured option-snapshot error despite a usable pre-aborted signal, would fail at least one variant. T-API-65g already proves the principle on the throwing-`env`-getter-on-options-object surface; this test extends the principle systematically across the full invalid-`maxIterations` enumeration plus the representative remaining option-snapshot families. *(Spec 9.2, 9.3, 9.5)*
+- **T-API-65q**: `run()` — pre-aborted signal beats **the full enumerated invalid `maxIterations` set plus a representative selection of remaining option-snapshot failures**. Generator-surface counterpart to T-API-65p. Same parameterized variant set (i)–(xvi) — exhaustive over invalid `maxIterations` values (i)–(vi) (including `Infinity`, `null`, and string value variants alongside the numeric-range and `NaN` variants) and representative over the remaining option-snapshot families (vii)–(xvi) (invalid `cwd` / `envFile` types, throwing getters, representative invalid `env` shape and entry value, throwing `env` entry getter, throwing `env` proxy `ownKeys` trap, throwing `env` proxy `get` trap on an included key, throwing `options.maxIterations` getter) — and the same construction rule: build the **final options object directly** — for getter / proxy variants (viii), (x), (xiii), (xiv), (xv), (xvi), install the throwing accessor or proxy directly on the object passed to `run()` using `Object.defineProperty` or field-by-field construction; **never via `{ ...opts, ... }`**, because spreading invokes enumerable getters, proxy `ownKeys` traps, and proxy `get` traps in the test harness before `run()` is called (see "Test-construction sanity for getter/proxy variants" in section 1.3). For variants (i)–(vi) the `maxIterations` default of `1` may be replaced by the variant value or omitted entirely. The full invalid `env` shape/value matrix is intentionally **not** exhaustively re-parameterized here; tests at the env-shape-validation surface (T-API-53–55, T-API-55a–55d) carry the exhaustive env-shape coverage without abort-precedence pinning, while this test pins the abort-precedence outcome via representative env variants. Drive each variant: `const c = new AbortController(); c.abort(); const gen = run("ralph", opts); await expect(gen.next()).rejects.toThrow(/abort/i);` Assert per variant: (a) the first `next()` throws the **abort** error — not the configured option-snapshot error, (b) no child was spawned, (c) no `loopx-*` tmpdir was created. **Test-construction sanity check** as in T-API-65p: for variants (i)–(vi), `opts.maxIterations` must be the variant value (`-1`, `1.5`, `NaN`, `Infinity`, `null`, or `"1"`) before invocation; for getter / proxy variants (viii), (x), (xiii), (xiv), (xv), (xvi), the test must guard against accidental harness-side invocation by avoiding object-spread of objects whose getters / proxy traps are the behavior under test. T-API-65f already proves the principle on the throwing-`env`-getter-on-options-object surface for `run()`; this test extends the principle systematically across the full invalid-`maxIterations` enumeration plus the representative remaining option-snapshot families on the generator surface. Together with T-API-65p, this closes the abort-precedence-over-option-snapshot category across both API surfaces. *(Spec 9.1, 9.3, 9.5)*
+- **T-API-65f**: `run()` — pre-aborted signal beats a throwing later-option getter. Per SPEC 9.1 "Option-snapshot timing" and SPEC 9.5 "`signal`", `options.signal` is read **before** other `RunOptions` fields, so an already-aborted signal is captured before any subsequent option-field read can produce a snapshot exception. Drive: `const c = new AbortController(); c.abort(); const throwingOpts = { signal: c.signal, get env() { throw new Error("env-getter-boom"); }, maxIterations: 1 }; const gen = run("ralph", throwingOpts); await expect(gen.next()).rejects.toThrow(/abort/i);` Assert: (a) the first-`next()` error is the abort error, **not** the `env-getter-boom` option-snapshot error, (b) no child was spawned (marker file absent if any), (c) no tmpdir was created. A buggy implementation that read `options.env` before `options.signal` would surface `env-getter-boom` instead and fail this test. This directly exercises the "signal first" rule rather than merely inferring it from the abort-vs-pre-iteration-failure precedence tests (T-API-65–65d). *(Spec 9.1, 9.3, 9.5)*
+- **T-API-65g**: `runPromise()` — pre-aborted signal beats a throwing later-option getter. Same fixture as T-API-65f: `const c = new AbortController(); c.abort(); const throwingOpts = { signal: c.signal, get env() { throw new Error("env-getter-boom"); }, maxIterations: 1 }; const p = runPromise("ralph", throwingOpts);` Assert: (a) the promise rejects with the abort error, **not** the `env-getter-boom` option-snapshot error, (b) no child was spawned, (c) no tmpdir was created. Per SPEC 9.2 "Option-snapshot timing" ("Identical to `run()`: each option field read at most once, `options.signal` first"), the same signal-first rule holds under `runPromise()`. This is the `runPromise()` counterpart to T-API-65f and completes signal-first coverage across both API surfaces. *(Spec 9.2, 9.3, 9.5)*
+- **T-API-66**: Abort after final yield but before settlement produces abort error. Mirror T-TMP-23 / Spec 9.3 "Abort after final yield". `const gen = run("ralph", { signal: c.signal, maxIterations: 1 }); const { value } = await gen.next(); c.abort(); await gen.next();` — expect the second `next()` to throw the abort error, not to resolve `{ done: true }` silently. *(Spec 9.3)*
+- **T-API-66a**: Abort after final yield but before settlement produces abort error on subsequent `.return()`. Per SPEC 9.3: "Abort after final yield ... produces the abort error on the next generator interaction — `g.next()`, `.return()`, or `.throw()`." T-API-66 covers the `.next()` branch; this covers `.return()`. `const gen = run("ralph", { signal: c.signal, maxIterations: 1 }); const { value } = await gen.next(); c.abort(); await expect(gen.return(undefined)).rejects.toThrow(<abort error>);` Assert the `.return()` call rejects with the abort error rather than settling `{ done: true, value: undefined }` silently. *(Spec 9.3, 9.1)*
+- **T-API-66b**: Abort after final yield but before settlement produces abort error on subsequent `.throw()`. Same setup as T-API-66a. `const gen = run("ralph", { signal: c.signal, maxIterations: 1 }); const { value } = await gen.next(); c.abort(); await expect(gen.throw(new Error("consumer-err"))).rejects.toThrow(<abort error>);` Assert the `.throw()` call rejects with the **abort** error (the signal displaces the consumer-supplied error, per SPEC 9.3's abort-after-final-yield rule). Together, T-API-66 / T-API-66a / T-API-66b cover all three settle-triggering interactions enumerated in SPEC 9.3 under the **`maxIterations`-reached** final-yield trigger. *(Spec 9.3, 9.1)*
+- **T-API-66c**: Abort after **`stop: true`-driven** final yield but before settlement produces abort error. Companion to T-API-66 for the script-driven final-yield branch. SPEC 9.3 says the final `Output` may be final because of "`stop: true` or `maxIterations` reached" — the abort-after-final-yield rule applies symmetrically across both triggers. T-API-66 covers the `maxIterations: 1`-driven final-yield case; this test pins down the `stop: true`-driven case so a buggy implementation that recognized "final yield" only when the iteration counter reached the limit (and treated `stop: true` as a separate "the script asked to stop, settle silently" code path that bypassed abort-precedence) would pass T-API-66 yet silently resolve `{ done: true }` on the next `.next()` despite the live abort. Set up `.loopx/ralph/index.sh` that emits `{"stop":true}` on its first iteration. Drive: `const c = new AbortController(); const gen = run("ralph", { signal: c.signal, maxIterations: 5 }); const first = await gen.next();` (the iteration limit is `5`, but the script's `stop: true` makes the first yielded `Output` final). Verify `first.value.stop === true`. Then `c.abort(); await expect(gen.next()).rejects.toThrow(<abort error>);` Assert: (a) the second `.next()` rejects with the **abort** error, **not** `{ done: true }`, (b) the rejection error is the abort error class (matching T-API-66's abort-error contract), and (c) cleanup ran before the rejection surfaced (assertion shape mirrors T-TMP-24a's "tmpdir removed before throw" assertion; pin down the cleanup-ordering side via the T-TMP-24e companion test below). A buggy implementation that special-cased `stop: true` to skip the abort-precedence check would silently resolve `{ done: true }` and fail (a). *(Spec 9.3, 9.1)*
+- **T-API-66d**: Abort after **`stop: true`-driven** final yield produces abort error on subsequent `.return()`. `.return()` counterpart to T-API-66c, mirroring T-API-66a's relationship to T-API-66. Same fixture as T-API-66c (script emits `{"stop":true}` on first iteration). Drive: `const c = new AbortController(); const gen = run("ralph", { signal: c.signal, maxIterations: 5 }); const first = await gen.next(); /* first.value.stop === true */ c.abort(); await expect(gen.return(undefined)).rejects.toThrow(<abort error>);` Assert the `.return()` call rejects with the abort error rather than settling `{ done: true, value: undefined }` silently. The abort-after-final-yield rule applies regardless of which settlement-triggering interaction follows — `.next()` (T-API-66c) and `.return()` (this test) must both surface the abort, not silent settlement. *(Spec 9.3, 9.1)*
+- **T-API-66e**: Abort after **`stop: true`-driven** final yield produces abort error on subsequent `.throw()`, displacing the consumer-supplied error. `.throw()` counterpart to T-API-66c / T-API-66d, mirroring T-API-66b's relationship to T-API-66 / T-API-66a. Same fixture (script emits `{"stop":true}` on first iteration). Drive: `const c = new AbortController(); const gen = run("ralph", { signal: c.signal, maxIterations: 5 }); const first = await gen.next(); /* first.value.stop === true */ c.abort(); await expect(gen.throw(new Error("consumer-err"))).rejects.toThrow(<abort error>);` Assert the `.throw()` call rejects with the **abort** error (the signal displaces the consumer-supplied error per SPEC 9.3's abort-after-final-yield rule, identical contract to T-API-66b but driven by the `stop: true` final-yield trigger rather than `maxIterations`-reached). Together with T-API-66c (`.next()`) and T-API-66d (`.return()`), this test closes coverage for all three settle-triggering interactions × the `stop: true`-driven final-yield trigger, completing the T-API-66/66a/66b × `stop: true`/`maxIterations` matrix. *(Spec 9.3, 9.1)*
+
+##### Pinned Priority
+
+- **T-API-67**: `run()` — invalid `options.cwd` (non-string) surfaces before all four project-root-dependent failures named in Spec 9.3. Parameterize over fixture variants that would otherwise fail via (a) `.loopx/` discovery error, (b) env-file loading error, (c) target-resolution error, and (d) tmpdir-creation error. In every variant, assert the first `next()` throws the invalid-`cwd` error, not the downstream project-root-dependent failure. *(Spec 9.3, 9.5)*
+- **T-API-67a**: `run()` — throwing `options.cwd` getter surfaces before the same four project-root-dependent failures as T-API-67. Parameterize over the same variants; in every case, assert the first `next()` throws the `cwd`-getter error, not the downstream failure. *(Spec 9.3, 9.5)*
+- **T-API-67b**: `run()` — invalid `options.envFile` (non-string) surfaces before downstream project-root-dependent failures. Parameterize over fixture variants that would otherwise fail via (a) `.loopx/` discovery error, (b) **env-file-loading error** (a global env file present and unreadable, or otherwise configured to surface a load-failure independent of the invalid `envFile` path — e.g., a global `XDG_CONFIG_HOME/loopx/env` of mode `000`), (c) target-resolution error, and (d) tmpdir-creation error. Assert the first `next()` throws the invalid-`envFile` error in every variant. SPEC 9.3 names all four project-root-dependent failures (discovery, env-file loading, target resolution, tmpdir creation) as the set that pinned `options.envFile`-validation must precede; this test exercises the env-file-loading branch alongside the other three. (Note: the *invalid `envFile`* path's own load is never reached because shape validation fires first; the env-file-loading branch is exercised via the **independent** global env file's load failure, which would otherwise have been the surfaced error.) Variant (b) is **conditional on `process.getuid() !== 0`** — root bypasses POSIX permission checks. *(Spec 9.3, 9.5)*
+- **T-API-67c**: `run()` — throwing `options.envFile` getter surfaces before the same downstream project-root-dependent failures as T-API-67b, including the env-file-loading branch. Parameterize over the same four variants (discovery, **env-file loading**, target resolution, tmpdir creation); in every case, assert the first `next()` throws the `envFile`-getter error, not the downstream failure. The env-file-loading variant uses an independently-failing global env file (mode `000` `XDG_CONFIG_HOME/loopx/env` or equivalent) so that shape-validation pinning is observable against a real env-file-load failure, not just the invalid `envFile` path's own deferred load. **Conditional on `process.getuid() !== 0`** for the env-file-loading variant. *(Spec 9.3, 9.5)*
+- **T-API-67d**: `runPromise()` counterpart to T-API-67 — invalid `options.cwd` (non-string) surfaces before the same four project-root-dependent failures (discovery, env-file loading, target resolution, tmpdir creation). Assert the promise rejects with the invalid-`cwd` error, not the downstream failure. *(Spec 9.3, 9.5)*
+- **T-API-67e**: `runPromise()` counterpart to T-API-67a — throwing `options.cwd` getter surfaces before the same four project-root-dependent failures. Assert the promise rejects with the `cwd`-getter error, not the downstream failure. *(Spec 9.3, 9.5)*
+- **T-API-67f**: `runPromise()` counterpart to T-API-67b — invalid `options.envFile` (non-string) surfaces before the same four downstream project-root-dependent failures (discovery, **env-file loading**, target resolution, tmpdir creation). The env-file-loading variant uses an independently-failing global env file (mode `000` `XDG_CONFIG_HOME/loopx/env` or equivalent) so the load-failure path is exercised against the invalid-`envFile`-pinning rule rather than the invalid `envFile`'s own deferred load. Assert the promise rejects with the invalid-`envFile` error in every variant. **Conditional on `process.getuid() !== 0`** for the env-file-loading variant. *(Spec 9.3, 9.5)*
+- **T-API-67g**: `runPromise()` counterpart to T-API-67c — throwing `options.envFile` getter surfaces before the same four downstream project-root-dependent failures (discovery, **env-file loading**, target resolution, tmpdir creation). Same env-file-loading-variant configuration as T-API-67f. Assert the promise rejects with the `envFile`-getter error, not the downstream failure, in every variant. **Conditional on `process.getuid() !== 0`** for the env-file-loading variant. *(Spec 9.3, 9.5)*
+
+##### Pre-First-`next()` Carve-out
+
+Spec 9.1 defines a carve-out: `.return()` or `.throw()` as the consumer's *first* interaction with the generator returned by `run()` settles silently, suppressing all pre-iteration errors.
+
+- **T-API-68**: `.return()` as first interaction suppresses invalid-target error. `const gen = run(undefined as any); await gen.return(undefined);` Assert no error is thrown. No child is spawned, no tmpdir created. *(Spec 9.1)*
+- **T-API-68a**: `.return()` as first interaction suppresses discovery failure. Call in a fixture without `.loopx/`. `const gen = run("ralph"); await gen.return(undefined);` Assert no error. *(Spec 9.1)*
+- **T-API-68b**: `.return()` as first interaction suppresses env-file-load failure. `const gen = run("ralph", { envFile: "nonexistent.env" }); await gen.return(undefined);` Assert no error. *(Spec 9.1)*
+- **T-API-68c**: `.return()` as first interaction suppresses option-snapshot failure. `const gen = run("ralph", { maxIterations: -1 }); await gen.return(undefined);` Assert no error. *(Spec 9.1)*
+- **T-API-68d**: `.return()` as first interaction suppresses pre-aborted signal. `const c = new AbortController(); c.abort(); const gen = run("ralph", { signal: c.signal }); await gen.return(undefined);` Assert no error. Per Spec 9.1: "A `signal` captured at call time is not consulted; even an already-aborted signal does not surface the abort error through this path." *(Spec 9.1)*
+- **T-API-68e**: `.return()` as first interaction does not create a tmpdir. Snapshot `os.tmpdir()` before and after the `.return()` call. Assert no new `loopx-*` directory was created. *(Spec 9.1, 7.4)*
+- **T-API-68g**: `.return()` as first interaction suppresses tmpdir-creation failure. Configure a tmpdir-creation failure by setting `TMPDIR` to an unwritable path (e.g., a parent directory with mode 000) so that `mkdtemp` would fail pre-iteration. `const gen = run("ralph"); await gen.return(undefined);` Assert: (a) no error is thrown, (b) the `.return()` resolves cleanly with `{ done: true }`, (c) no `loopx-*` tmpdir exists under the configured unwritable parent (the only parent loopx would have attempted under this `TMPDIR` snapshot — assertion is scoped to that parent, not a global `os.tmpdir()` scan, per the test-parent isolation guidance in section 4.7's tmpdir-block preface), and (d) no tmpdir-creation-failure error, warning, or other surfacing of the configured failure appears on stderr or via the generator settlement — the pre-first-`next()` carve-out suppressed the configured tmpdir-creation failure entirely. (Whether loopx black-box "did not attempt `mkdtemp`" is not directly observable without a seam; assertions (c) and (d) together pin the observable outcome of suppression.) Per SPEC 9.1 "pre-first-`next()` consumer-cancellation carve-out": "tmpdir creation failures are all suppressed." T-API-68/68a–68d cover target / discovery / env-file / option / pre-aborted-signal suppression; T-API-68e covers the negative observation (no tmpdir created); this test closes the tmpdir-creation-failure branch enumerated in SPEC 9.1's carve-out list. **Conditional on `process.getuid() !== 0`.** *(Spec 9.1, 7.4)*
+- **T-API-68f**: `.return(value)` as first interaction settles with the supplied value per standard async-generator semantics. Per SPEC 9.1 "settles the generator per standard JS async-generator semantics" — the value propagates through the iterator result. `const gen = run(undefined as any); const result = await gen.return("my-return-value"); expect(result).toEqual({ value: "my-return-value", done: true });` Also verify the generator is exhausted: a subsequent `await gen.next()` resolves to `{ value: undefined, done: true }`. This pins down the value-propagation contract — T-API-68/68a–68d cover "no error is thrown" under the carve-out but do not verify that the iterator-result `value` field carries the consumer-supplied value. A buggy implementation that force-returned `{ value: undefined, done: true }` ignoring the passed-in value would pass T-API-68 but fail this assertion. *(Spec 9.1)*
+- **T-API-68h**: `.return()` as first interaction suppresses a throwing `options.env` getter. SPEC 9.1's pre-first-`next()` carve-out enumerates "throwing option-field getters" and "throwing `options.env` enumerable getters or proxy traps" among the snapshot errors that are suppressed when the consumer's first interaction is `.return()`. T-API-68c covers a plain invalid option (`maxIterations: -1`); this test pins down the throwing-getter branch specifically. Construct an options object with a throwing `env` getter: `const opts = {}; Object.defineProperty(opts, "env", { enumerable: true, get() { throw new Error("evil-env-getter"); } });` Drive: `const gen = run("ralph", opts); const settled = await gen.return(undefined);` Assert: (a) `settled` resolves to `{ done: true, value: undefined }` — no error is thrown, (b) no child spawned (no marker), (c) no `loopx-*` tmpdir created (consistent with T-API-68e), and (d) stderr does not surface the `"evil-env-getter"` error. Per the carve-out: captured option-snapshot errors — including throwing `env` getters on the options object — are fully suppressed. An implementation that re-invoked the getter during settlement, or that propagated the captured snapshot error despite the carve-out, would fail this test. *(Spec 9.1, 9.5)*
+- **T-API-68j**: `.return(value)` as first interaction suppresses an abort that fires on a **live** signal *between* `run()` returning and the consumer's first interaction. SPEC 9.1's pre-first-`next()` carve-out: "A `signal` captured at call time is not consulted; even an already-aborted signal does not surface the abort error through this path." T-API-68d covers the **already-aborted-at-call-time** case (the signal was aborted *before* `run()` was called, so the listener never fires for a fresh state transition). This test covers the **live-signal-aborts-after-call-time** case: the signal is **not aborted** when `run()` is called (so the abort listener registered at call time per T-API-64k attaches to a live, not-yet-aborted signal), then the consumer aborts the signal **before** their first interaction with the generator (so the listener actually fires for a state transition observed by loopx), and *then* the consumer's first interaction is `.return(value)`. The carve-out must still apply: even though the abort listener has fired and loopx has observed a state transition on the captured signal, the consumer's first interaction being `.return()` settles per standard async-generator semantics with no abort-error surfacing. This pins down the stronger "captured signal is not consulted" reading — the captured signal is not consulted *even when its state transitioned during the carve-out window* — over the weaker reading "captured signal is not consulted only if it never transitioned." Construct: `const c = new AbortController(); const gen = run("ralph", { signal: c.signal }); c.abort(); /* listener fires synchronously */ const result = await gen.return("my-return-value");` Assert: (a) `result` resolves to `{ value: "my-return-value", done: true }` — standard async-generator `.return()` settlement, with the consumer-supplied value propagated per the same contract as T-API-68f, (b) **no abort error is thrown** — the carve-out suppresses the abort observation that fired on the captured signal, (c) no child is spawned (no marker file written; assertion-scoped to the test fixture), and (d) **no `loopx-*` tmpdir is created** under the test-isolated tmpdir parent (per the section 4.7 tmpdir-block preface). T-API-68d covers pre-aborted suppression (no listener fires) and T-API-68e / T-API-68g cover the no-tmpdir / suppressed-tmpdir-failure observations on the `.return()` path; this test fills the "live signal aborts after call but before first interaction" gap that the existing tests do not directly exercise. A buggy implementation that surfaced the abort because the listener fired during the carve-out window (rather than because the signal was consulted on the carve-out path) would fail (b). *(Spec 9.1, 9.5)*
+- **T-API-68k**: `.return()` as first interaction suppresses a throwing `options.signal` getter. SPEC 9.1's pre-first-`next()` carve-out enumerates "throwing option-field getters" — including the `signal` getter, which SPEC 9.1 reads first per the option-snapshot ordering rule — among the snapshot errors that are suppressed when the consumer's first interaction is `.return()`. T-API-68h covers the `options.env` getter on the options object (which is read after `signal`); this test pins down the **`signal`-getter** branch specifically so a buggy implementation that surfaced a `signal`-snapshot exception despite the carve-out — perhaps because `signal` is read first and the carve-out check fires later in the call-time sequence — would be caught. Construct an options object with a throwing `signal` getter: `const opts = {}; Object.defineProperty(opts, "signal", { enumerable: true, get() { throw new Error("evil-signal-getter"); } });` Drive: `const gen = run("ralph", opts); const settled = await gen.return(undefined);` Assert: (a) `settled` resolves to `{ done: true, value: undefined }` — no error is thrown, (b) no child spawned, (c) no `loopx-*` tmpdir created (consistent with T-API-68e), and (d) stderr does not surface the `"evil-signal-getter"` error. Per the carve-out: captured option-snapshot errors — including throwing getters on every pinned `RunOptions` field — are fully suppressed when the consumer's first interaction is `.return()`. *(Spec 9.1, 9.5)*
+- **T-API-68l**: `.return()` as first interaction suppresses a throwing `options.cwd` getter. Pinned-priority option per SPEC 9.3 "Pinned pre-iteration priority". Companion to T-API-68k; pins down the throwing-`cwd`-getter branch of the carve-out's "throwing option-field getters" enumeration. Construct: `const opts = {}; Object.defineProperty(opts, "cwd", { enumerable: true, get() { throw new Error("evil-cwd-getter"); } });` Drive: `const gen = run("ralph", opts); const settled = await gen.return(undefined);` Assert: (a) `settled` resolves to `{ done: true, value: undefined }`, (b) no child spawned, (c) no `loopx-*` tmpdir created, and (d) stderr does not surface the `"evil-cwd-getter"` error. A buggy implementation that surfaced the pinned-priority `cwd`-getter exception under the carve-out path would fail (a). *(Spec 9.1, 9.5)*
+- **T-API-68m**: `.return()` as first interaction suppresses a throwing `options.envFile` getter. Pinned-priority option per SPEC 9.3 "Pinned pre-iteration priority". Companion to T-API-68k / T-API-68l; pins down the throwing-`envFile`-getter branch. Construct: `const opts = {}; Object.defineProperty(opts, "envFile", { enumerable: true, get() { throw new Error("evil-envFile-getter"); } });` Drive: `const gen = run("ralph", opts); const settled = await gen.return(undefined);` Assert: (a) `settled` resolves to `{ done: true, value: undefined }`, (b) no child spawned, (c) no `loopx-*` tmpdir created, and (d) stderr does not surface the `"evil-envFile-getter"` error. *(Spec 9.1, 9.5)*
+- **T-API-68n**: `.return()` as first interaction suppresses a throwing `options.maxIterations` getter. Companion to T-API-68k / T-API-68l / T-API-68m; pins down the throwing-`maxIterations`-getter branch. Construct: `const opts = {}; Object.defineProperty(opts, "maxIterations", { enumerable: true, get() { throw new Error("evil-maxIterations-getter"); } });` Drive: `const gen = run("ralph", opts); const settled = await gen.return(undefined);` Assert: (a) `settled` resolves to `{ done: true, value: undefined }`, (b) no child spawned, (c) no `loopx-*` tmpdir created, and (d) stderr does not surface the `"evil-maxIterations-getter"` error. Together with T-API-68k / T-API-68l / T-API-68m / T-API-68h, this completes coverage for throwing getters on every pinned `RunOptions` field — `signal`, `cwd`, `envFile`, `maxIterations`, `env` — under the `.return()` carve-out. *(Spec 9.1, 9.5)*
+- **T-API-68o**: `.return()` as first interaction suppresses an **unreadable global env file** failure. SPEC 9.1's carve-out enumerates "env-file loading failures" — covering both local (`-e` / `RunOptions.envFile`, SPEC 8.2) and global (`$XDG_CONFIG_HOME/loopx/env`, SPEC 8.1) env files per SPEC 7.1 step 2. T-API-68b covers the local missing-envFile sub-path; this test pins down the global-env-file unreadable sub-path so an implementation that suppressed local env-file failures via the carve-out path but routed unreadable global env files through a different, suppression-blind code path (e.g., a synchronous `fs.readFileSync` that throws and is rethrown before the carve-out check) would be caught. Set up: an isolated `XDG_CONFIG_HOME` (e.g., `<test-dir>/xdg-config`) with `loopx/env` written and then `chmod 000`'d so it exists but is unreadable; this `XDG_CONFIG_HOME` is injected into loopx's inherited environment (the same injection pattern as T-TMP-12-global-env-unreadable / T-API-65r). A valid `.loopx/ralph/index.sh`. Drive: `const gen = run("ralph"); const settled = await gen.return(undefined);` Assert: (a) `settled` resolves to `{ done: true, value: undefined }` — no error is thrown, (b) no child spawned, (c) no `loopx-*` tmpdir created, and (d) stderr does not surface the global-env-file-read error. Together with T-API-65r (abort-precedence over the same failure mode) and T-SIG-30 (CLI signal-wins), this closes the global-env-unreadable sub-path on the `.return()` carve-out surface. **Conditional on `process.getuid() !== 0`** (root can read mode-000 files). *(Spec 9.1, 8.1, 7.1)*
+- **T-API-68p**: `.return()` as first interaction suppresses **local env-file parser warnings**. SPEC 9.1's carve-out says "the loop body is never entered. **No pre-iteration step runs and no pre-iteration error is surfaced**" — the "no pre-iteration step runs" clause is broader than the enumerated error list and applies to *warning-only* pre-iteration work as well as failure paths. T-API-68b / T-API-68o pin down env-file *failure* suppression (missing local file, unreadable global file); this test pins down env-file *warning* suppression on the local-`envFile` path: a malformed-but-readable local env file would normally produce a SPEC 8.1 invalid-key parser warning on stderr (e.g., the `1BAD=val` line is ignored with a warning per T-CLI-22c / T-ENV-15c), but the carve-out must suppress that warning because the env-file parsing step never runs. Set up: a project root with a valid `.loopx/ralph/index.sh`. Write a local env file (e.g., `<test-dir>/local.env`) with content `1BAD=val\nOK=fine\n` (the `1BAD` line is the SPEC 8.1 invalid-key warning trigger; the `OK=fine` line would parse normally). Drive: `const gen = run("ralph", { envFile: "<test-dir>/local.env" }); const settled = await gen.return(undefined);` Assert: (a) `settled` resolves to `{ done: true, value: undefined }` — no error is thrown, (b) no child spawned (no marker file from `ralph:index`), (c) no `loopx-*` tmpdir created (assertion-scoped to the test-isolated tmpdir parent), and (d) **stderr does not contain the SPEC 8.1 invalid-key parser warning for `1BAD`** — i.e., stderr does not mention `1BAD` and does not surface the env-file invalid-key warning text. A buggy implementation that ran the env-file parse step (producing the warning) before checking whether the consumer had already canceled via `.return()` would fail (d) — the warning would leak to stderr even though no error was surfaced. This test, paired with T-API-68b (missing-file failure suppression on the same `envFile` path), pins down both error and warning suppression on the local env-file pre-iteration step. *(Spec 9.1, 8.1, 8.2, 7.1)*
+- **T-API-68q**: `.return()` as first interaction suppresses **global env-file parser warnings**. Global-env-file counterpart to T-API-68p. SPEC 8.1's "Key validation" rule applies symmetrically to global and local env files — both emit invalid-key warnings on stderr when a malformed-but-readable line is encountered. T-API-68p covers local env-file warning suppression via the `envFile` path; this test covers global env-file warning suppression via the inherited `XDG_CONFIG_HOME` path that loopx resolves on its own (no `envFile` option supplied). T-API-68o covers the global-env-file *failure* path (mode 000 — unreadable); this test covers the *warning* path (readable but malformed). Set up: an isolated `XDG_CONFIG_HOME` (e.g., `<test-dir>/xdg-config`) with `loopx/env` written and containing `1BAD=val\nOK=fine\n` (the `1BAD` line is the SPEC 8.1 invalid-key warning trigger). The `XDG_CONFIG_HOME` is injected into loopx's inherited environment (same injection pattern as T-API-68o / T-TMP-12-global-env-unreadable). A valid `.loopx/ralph/index.sh`. Drive: `const gen = run("ralph"); const settled = await gen.return(undefined);` Assert: (a) `settled` resolves to `{ done: true, value: undefined }` — no error is thrown, (b) no child spawned, (c) no `loopx-*` tmpdir created, and (d) **stderr does not contain the SPEC 8.1 invalid-key parser warning for `1BAD`** — the global-env-file parse step never ran. Together with T-API-68p (local) and T-API-68o (global-failure), this closes the global-env-file warning-suppression branch of SPEC 9.1's "no pre-iteration step runs" clause. *(Spec 9.1, 8.1, 7.1)*
+- **T-API-68r**: `.return()` as first interaction suppresses **workflow `package.json` warnings** from the starting-workflow version check (SPEC 7.1 step 5). SPEC 3.2 enumerates four `package.json` failure modes that produce warnings on stderr at runtime: unsatisfied semver range (T-VER-01), invalid JSON (T-VER-08 / T-VER-09), invalid semver range (T-VER-09a), and unreadable `package.json` (T-VER-07). T-TMP-12f / T-TMP-12f2 / T-TMP-12f3 / T-TMP-12f4 pin down that step 5 runs *before* tmpdir creation in the CLI surface and emits each of these four warnings even when step 6 fails. The `.return()` carve-out's "no pre-iteration step runs" clause must additionally suppress those warnings entirely when the consumer cancels before first `next()`: step 5 never executes, so no `package.json` warning fires. **Parameterize over the four warning branches** to ensure all four `package.json` failure-mode warnings are suppressed: **(i) unsatisfied range** — `.loopx/ralph/package.json` declares `{ "dependencies": { "loopx": ">=999.0.0" } }`; **(ii) invalid JSON** — `.loopx/ralph/package.json` contains `{broken`; **(iii) invalid semver range** — `.loopx/ralph/package.json` contains `{ "dependencies": { "loopx": "not-a-range!!!" } }`; **(iv) unreadable `package.json`** — `.loopx/ralph/package.json` contains valid content (e.g., `{ "dependencies": { "loopx": "*" } }`) and is `chmod 000`'d so it exists but is unreadable. Each variant has a valid `.loopx/ralph/index.sh`. For each variant, drive: `const gen = run("ralph"); const settled = await gen.return(undefined);` Assert (per variant): (a) `settled` resolves to `{ done: true, value: undefined }` — no error is thrown, (b) no child spawned, (c) no `loopx-*` tmpdir created, and (d) **stderr does not contain the `package.json` warning text** for that variant (no version-mismatch / invalid-JSON / invalid-semver / unreadable-`package.json` warning surfaces, even though SPEC 3.2 enumerates them as runtime warnings on workflow entry). Variant (iv) is **conditional on `process.getuid() !== 0`** (root can read mode-000 files). T-CLI-119 / T-CLI-119c / T-CLI-119e / T-CLI-119f cover the analogous CLI-`-n 0` carve-out (the `-n 0` short-circuit similarly skips step 5); this test pins down the `.return()` carve-out's symmetric warning-suppression on the programmatic surface. A buggy implementation that read and parsed `package.json` (producing the warning) before checking whether the consumer had already canceled via `.return()` would fail (d) on each variant. *(Spec 9.1, 7.1, 3.2)*
+- **T-API-68i**: `.return()` as first interaction suppresses **the full enumerated invalid `maxIterations` set plus a representative selection of remaining option-snapshot and target-resolution failures**. SPEC 9.1's pre-first-`next()` carve-out lists "captured option-snapshot errors (invalid `options` values, invalid `options.signal`, non-string `options.cwd` / `options.envFile`, invalid `options.maxIterations`, invalid `options.env` shape, throwing option-field getters, throwing `options.env` enumerable getters or proxy traps), invalid `target` values and target-syntax validation, `.loopx/` discovery failures, env-file loading failures, target resolution failures, and tmpdir creation failures" — all suppressed. Existing T-API-68 / 68a–68h / 68k–68o pin down individual branches (target-syntax, discovery, env-file load, single `maxIterations: -1` option-snapshot, pre-aborted signal, no-tmpdir negative observation, return-value propagation, tmpdir-creation failure, throwing `options.env` getter, throwing `options.signal` / `options.cwd` / `options.envFile` / `options.maxIterations` getters, unreadable global env file); this test extends coverage to (i) the **full enumerated invalid `maxIterations` set** (every value treated as invalid in the validation matrix at T-API-22 etc., parameterized exhaustively so the carve-out × `maxIterations` matrix is a strict superset of the validation matrix), (ii) a **representative selection** of the remaining option-snapshot families (invalid `options` shape, invalid `options.signal`, invalid `cwd` / `envFile` types, representative invalid `env` shape and entry value, throwing `env` entry getter, throwing `env` proxy traps), (iii) the target-resolution sub-paths, and (iv) target-syntax validation — in a single parameterized test, mirroring the parameterized T-API-69g but for the `.return()` surface. The full invalid `env` shape/value matrix (every shape from T-API-53–53d and every entry-value variant from T-API-54–54c) is intentionally **not** exhaustively re-parameterized here — those validation paths converge on a single "captured option-snapshot error" code path that the carve-out must suppress, and the representative sample is sufficient to detect a buggy implementation that bypassed the carve-out on the option-snapshot category; T-API-53–55 and T-API-55a–55d carry the exhaustive env-shape coverage without carve-out pinning. **Parameterize over each variant**, set up the relevant fixture, drive `const gen = run(<target>, <opts>); const settled = await gen.return(undefined);` and assert per variant: (a) `settled` resolves to `{ done: true, value: undefined }` — no error is thrown, (b) no child spawned (no marker file written), (c) no `loopx-*` tmpdir is created (assertion is scoped to the test-isolated tmpdir parent per the section 4.7 tmpdir-block preface), and (d) stderr does not surface the configured error. **Variants:** **(i) invalid `options` shape — `null`** (`run("ralph", null as any)`); **(ii) invalid `options` shape — array** (`run("ralph", [] as any)`); **(iii) invalid `options` shape — function** (`run("ralph", (() => {}) as any)`); **(iv) invalid `options` shape — primitive number** (`run("ralph", 42 as any)`); **(v) invalid `options.signal` — non-`AbortSignal`-shaped value** (`run("ralph", { signal: "not-a-signal" as any })`); **(vi) non-string `options.cwd`** (`run("ralph", { cwd: 42 as any })`); **(vii) non-string `options.envFile`** (`run("ralph", { envFile: 42 as any })`); **(viii) invalid `options.maxIterations: 1.5`** (`run("ralph", { maxIterations: 1.5 })` — non-integer; T-API-68c covers `-1` separately); **(ix) invalid `options.maxIterations: NaN`** (`run("ralph", { maxIterations: NaN })`); **(x) invalid `options.maxIterations: Infinity`** (`run("ralph", { maxIterations: Infinity })` — non-finite); **(xi) invalid `options.maxIterations: null as any`** (`run("ralph", { maxIterations: null as any })` — null is not a finite non-negative integer); **(xii) invalid `options.maxIterations: "1" as any`** (`run("ralph", { maxIterations: "1" as any })` — string value rejected at the type-shape gate, distinct from the numeric-range gates of (viii)–(xi)); **(xiii) representative invalid `options.env` shape — array** (`run("ralph", { env: [] as any })` — representative sample of the SPEC 9.5 / T-API-53–53d shape-validation matrix); **(xiv) representative invalid `options.env` non-string entry value** (`run("ralph", { env: { KEY: 42 as any } })` — representative sample of the SPEC 9.5 / T-API-54–54c entry-value-validation matrix); **(xv) throwing `options.env` proxy `ownKeys` trap** — construct `const env = new Proxy({}, { ownKeys() { throw new Error("ownKeys-trap-boom"); } });` and call `run("ralph", { env })`; **(xvi) target-resolution — missing workflow** (fixture has `.loopx/other/index.sh`; call `run("ralph")`); **(xvii) target-resolution — missing script in existing workflow** (fixture has `.loopx/ralph/index.sh`; call `run("ralph:check")`); **(xviii) target-resolution — missing default `index`** (fixture has `.loopx/ralph/check.sh` only; call bare `run("ralph")`); **(xix) invalid target syntax** — call `run("a:b:c")` (three-segment target violates the `<workflow>[:<script>]` grammar; this exercises the target-syntax-validation branch of SPEC 9.1's carve-out, distinct from T-API-68's `undefined`-target argument-validation case and from variants (xvi)–(xviii)'s post-syntax target-resolution branches); **(xx) throwing enumerable getter inside `options.env`** — construct `const env = {}; Object.defineProperty(env, "KEY", { enumerable: true, get() { throw new Error("env-entry-getter-boom"); } });` and call `run("ralph", { env })` (this exercises the "throwing enumerable getters inside `options.env`" sub-clause of SPEC 9.1's carve-out, distinct from variant (xv)'s proxy `ownKeys` trap and from T-API-68h's throwing getter on the **options object's `env` property** itself); **(xxi) throwing `options.env` proxy `getOwnPropertyDescriptor` trap** (observational on the trap-invocation axis) — construct `const env = new Proxy({ A: "a" }, { getOwnPropertyDescriptor() { throw new Error("descriptor-trap-boom"); } });` and call `run("ralph", { env })`. SPEC 9.1's carve-out covers "throwing `options.env` ... proxy traps" generally, but SPEC 9.5's snapshot-error enumeration names only the `ownKeys` trap explicitly; whether the descriptor trap is invoked during the snapshot is implementation-defined (see T-API-62f2). This variant exercises the carve-out only on implementations that invoke the descriptor trap and capture its throw — for those implementations, the captured exception must be suppressed under the carve-out. On implementations that do not invoke the descriptor trap, no exception is captured, the carve-out has nothing to suppress, and assertions (a)–(d) hold vacuously; **(xxii) throwing `options.env` proxy `get` trap** — construct `const env = new Proxy({ A: "a" }, { ownKeys() { return ["A"]; }, getOwnPropertyDescriptor(t, key) { return { enumerable: true, configurable: true, value: undefined, writable: true }; }, get() { throw new Error("get-trap-boom"); } });` and call `run("ralph", { env })` (extends proxy-trap suppression coverage to the value-read `get` trap; the `get` trap is necessarily invoked when loopx reads each entry's value, so this variant is a strict suppression pin — the captured snapshot exception must be suppressed under the carve-out, no vacuous-pass branch). Variant (xxi) is observational on the descriptor-trap-invocation axis; variant (xxii) is a strict suppression pin. For each variant, all four assertions (a)–(d) hold. The "no `loopx-*` tmpdir created" assertion (c) closes the negative observation that the carve-out short-circuited before tmpdir creation in every option-snapshot and target-resolution branch — a buggy implementation that performed tmpdir creation under the carve-out would fail this assertion in addition to whatever else it surfaced. **Variant (xvi)–(xviii) note:** these target-resolution sub-paths are distinct from the target-syntax-validation branch covered by variant (xix) and from T-API-68's argument-validation branch (which passed `undefined` as target). Together with T-API-68 and T-API-68a–68h, this test completes the `.return()` carve-out coverage across the SPEC 9.1 enumeration with exhaustive `maxIterations` coverage and representative env-shape coverage. *(Spec 9.1, 9.5, 7.1, 7.4, 4.1, 2.1)*
+- **T-API-69**: `.throw()` as first interaction — generator settles by throwing (consumer-supplied) error. `const gen = run(undefined as any); await expect(gen.throw(new Error("my-err"))).rejects.toThrow("my-err");` The consumer's error surfaces, not the invalid-target error. *(Spec 9.1)*
+- **T-API-69a**: `.throw()` as first interaction suppresses env-file-load failure. `await gen.throw(new Error("my-err"))` where gen was created with invalid envFile. Consumer-error surfaces, not env-file error. *(Spec 9.1)*
+- **T-API-69b**: `.throw()` as first interaction suppresses pre-aborted signal. Consumer-error surfaces, no abort error. *(Spec 9.1)*
+- **T-API-69c**: `.throw()` as first interaction does not create a tmpdir. *(Spec 9.1, 7.4)*
+- **T-API-69d**: `.throw()` as first interaction suppresses tmpdir-creation failure. Configure a tmpdir-creation failure by setting `TMPDIR` to an unwritable path (e.g., a parent directory with mode 000) so that `mkdtemp` would fail pre-iteration. `const gen = run("ralph"); await expect(gen.throw(new Error("my-err"))).rejects.toThrow("my-err");` Assert: (a) the consumer-supplied `"my-err"` surfaces (not the tmpdir-creation error), (b) no `loopx-*` tmpdir exists under the configured unwritable parent (the only parent loopx would have attempted under this `TMPDIR` snapshot — assertion is scoped to that parent, not a global `os.tmpdir()` scan, per the test-parent isolation guidance in section 4.7's tmpdir-block preface), and (c) no tmpdir-creation-failure error, warning, or other surfacing of the configured failure appears on stderr or via the rejected-promise / throw path — the pre-first-`next()` carve-out suppressed the configured tmpdir-creation failure entirely. (Whether loopx black-box "did not attempt `mkdtemp`" is not directly observable without a seam; assertions (b) and (c) together pin the observable outcome of suppression.) This is the `.throw()`-variant counterpart to T-API-68g (`.return()` carve-out vs tmpdir-creation failure), closing the tmpdir-creation-failure branch of SPEC 9.1's carve-out list for the `.throw()` surface too. **Conditional on `process.getuid() !== 0`.** *(Spec 9.1, 7.4)*
+- **T-API-69e**: `.throw()` as first interaction surfaces the consumer-supplied error even when a throwing `options.env` getter would otherwise have produced a snapshot error. Companion to T-API-68h. SPEC 9.1's pre-first-`next()` carve-out says: for `.throw()` as the first interaction, the consumer's error surfaces (per standard async-generator semantics) and the captured snapshot errors — including throwing `options.env` getters — are suppressed. Construct an options object with a throwing `env` getter: `const opts = {}; Object.defineProperty(opts, "env", { enumerable: true, get() { throw new Error("evil-env-getter"); } });` Drive: `const gen = run("ralph", opts); await expect(gen.throw(new Error("my-err"))).rejects.toThrow("my-err");` Assert: (a) the consumer-supplied `"my-err"` surfaces (not `"evil-env-getter"` and not any snapshot error), (b) no child spawned, (c) no `loopx-*` tmpdir created, and (d) stderr does not surface the `"evil-env-getter"` error. This is the `.throw()` counterpart to T-API-68h (`.return()` suppression of the same throwing getter), closing the throwing-`options.env`-getter branch of SPEC 9.1's carve-out list for the `.throw()` surface. *(Spec 9.1, 9.5)*
+- **T-API-69f**: `.throw()` as first interaction suppresses `.loopx/` discovery failure. SPEC 9.1's pre-first-`next()` carve-out enumerates "`.loopx/` discovery failures" among the suppressed pre-iteration errors. T-API-68a covers the `.return()` surface for this branch; this test is the symmetric `.throw()` counterpart, completing the discovery-failure coverage across both consumer-driven first-interaction surfaces. Set up a fixture without `.loopx/` (the standard missing-`.loopx/` condition from T-CLI-42 / T-DISC-10a). Drive: `const gen = run("ralph"); await expect(gen.throw(new Error("my-err"))).rejects.toThrow("my-err");` Assert: (a) the consumer-supplied `"my-err"` surfaces (not the missing-`.loopx/` discovery error), (b) no child spawned, (c) no `loopx-*` tmpdir created (snapshot the test-isolated tmpdir parent before / after; matches T-API-69c's no-tmpdir guarantee), and (d) stderr contains no missing-`.loopx/` discovery error or warning — the carve-out fully suppressed the discovery failure on the `.throw()` settlement, exactly mirroring T-API-68a's `.return()` suppression. A buggy implementation that surfaced the discovery error in addition to (or instead of) the consumer-supplied error would fail this test. *(Spec 9.1)*
+- **T-API-69g**: `.throw()` as first interaction suppresses target-resolution failures (missing workflow, missing script in existing workflow, missing default `index` for bare workflow target). SPEC 9.1's pre-first-`next()` carve-out enumerates "target resolution failures" among the suppressed pre-iteration errors; SPEC 7.1 step 3 enumerates three target-resolution sub-paths (missing workflow, missing script in an existing workflow, missing default entry point), and T-SIG-21 / T-SIG-27 / T-SIG-28 already cover all three on the CLI signal-wins surface and T-API-65h / T-API-65i / T-API-65j cover them on the abort-precedence surface. Existing `.return()` carve-out coverage (T-API-68 and friends) is largely structured around invalid-target / option / discovery / env-file / tmpdir branches but not the missing-workflow / missing-script / missing-index target-resolution sub-branches specifically. **Parameterize this test over the three target-resolution sub-paths**: (i) **missing workflow** — fixture with `.loopx/other/index.sh` (a different workflow), drive `run("ralph")`; (ii) **missing script in existing workflow** — fixture with `.loopx/ralph/index.sh` (workflow exists but no `check` script), drive `run("ralph:check")`; (iii) **missing default `index`** — fixture with `.loopx/ralph/check.sh` only (no `index.*`), drive bare `run("ralph")`. For each variant, drive `await expect(gen.throw(new Error("my-err"))).rejects.toThrow("my-err");` Assert (per variant): (a) the consumer-supplied `"my-err"` surfaces (not the target-resolution error of any of the three sub-paths), (b) no child spawned, (c) no `loopx-*` tmpdir created, and (d) stderr contains no target-resolution error or warning of the corresponding sub-path. This is the `.throw()` counterpart to T-API-68's invalid-target suppression but on the **target-resolution** branch (post-syntax, pre-spawn) rather than the syntax-validation branch — pinning down that all three SPEC 7.1 target-resolution sub-paths are suppressed under the carve-out for `.throw()`. Together with T-API-69 (invalid-target syntax — the implicit "target arg validation" branch of the carve-out) and T-API-69f (`.loopx/` discovery), this closes the `.throw()`-side coverage for the entire SPEC 9.1 carve-out list across consumer-driven first interactions, mirroring the existing `.return()` coverage. *(Spec 9.1, 7.1, 4.1, 2.1)*
+- **T-API-69i**: `.throw(err)` as first interaction surfaces the consumer-supplied error even when an abort fires on a **live** signal between `run()` returning and the consumer's `.throw()`. `.throw()` counterpart to T-API-68j. SPEC 9.1's pre-first-`next()` carve-out: "A `signal` captured at call time is not consulted; even an already-aborted signal does not surface the abort error through this path." T-API-69b covers the **already-aborted-at-call-time** case on the `.throw()` surface (no listener-firing transition); this test covers the **live-signal-aborts-after-call-time** case for `.throw()`, mirroring T-API-68j on the throw surface. The signal is **not aborted** at call time, the consumer aborts it **after** `run()` returns and **before** invoking `.throw()` (so the captured signal's abort listener actually fires on a transition observed by loopx), and the consumer's first interaction is `.throw(err)`. The carve-out must still apply: the consumer-supplied error surfaces per standard async-generator `.throw()` semantics, **not** the abort error that fired on the captured signal. Construct: `const c = new AbortController(); const gen = run("ralph", { signal: c.signal }); c.abort(); /* listener fires synchronously */ await expect(gen.throw(new Error("my-err"))).rejects.toThrow("my-err");` Assert: (a) the consumer-supplied `"my-err"` surfaces as the thrown / rejected error — **not** an abort error and **not** a combined error wrapping both, (b) no child is spawned (assertion-scoped to the test fixture), and (c) no `loopx-*` tmpdir is created under the test-isolated tmpdir parent (per the section 4.7 tmpdir-block preface). Together with T-API-68j (`.return(value)` counterpart), this test pins down the stronger "captured signal is not consulted *even when its state transitioned during the carve-out window*" reading on both consumer-driven first-interaction surfaces. A buggy implementation that surfaced the abort error in addition to (or instead of) `"my-err"` because the listener fired during the carve-out window would fail (a). *(Spec 9.1, 9.5)*
+- **T-API-69j**: `.throw()` as first interaction surfaces the consumer-supplied error even when a throwing `options.signal` getter would otherwise have produced a snapshot error. Companion to T-API-68k. SPEC 9.1's pre-first-`next()` carve-out enumerates "throwing option-field getters" — including the `signal` getter, which SPEC 9.1 reads first — among the snapshot errors that are suppressed when the consumer's first interaction is `.throw()`. T-API-69e covers the throwing `options.env` getter; this test pins down the throwing-`signal`-getter branch on the `.throw()` surface. Construct an options object with a throwing `signal` getter: `const opts = {}; Object.defineProperty(opts, "signal", { enumerable: true, get() { throw new Error("evil-signal-getter"); } });` Drive: `const gen = run("ralph", opts); await expect(gen.throw(new Error("my-err"))).rejects.toThrow("my-err");` Assert: (a) the consumer-supplied `"my-err"` surfaces (not `"evil-signal-getter"` and not any snapshot error), (b) no child spawned, (c) no `loopx-*` tmpdir created, and (d) stderr does not surface the `"evil-signal-getter"` error. *(Spec 9.1, 9.5)*
+- **T-API-69k**: `.throw()` as first interaction suppresses a throwing `options.cwd` getter. Pinned-priority option per SPEC 9.3. Companion to T-API-68l on the `.throw()` surface. Construct: `const opts = {}; Object.defineProperty(opts, "cwd", { enumerable: true, get() { throw new Error("evil-cwd-getter"); } });` Drive: `const gen = run("ralph", opts); await expect(gen.throw(new Error("my-err"))).rejects.toThrow("my-err");` Assert: (a) the consumer-supplied `"my-err"` surfaces (not `"evil-cwd-getter"`), (b) no child spawned, (c) no `loopx-*` tmpdir created, and (d) stderr does not surface the `"evil-cwd-getter"` error. *(Spec 9.1, 9.5)*
+- **T-API-69l**: `.throw()` as first interaction suppresses a throwing `options.envFile` getter. Pinned-priority option per SPEC 9.3. Companion to T-API-68m on the `.throw()` surface. Construct: `const opts = {}; Object.defineProperty(opts, "envFile", { enumerable: true, get() { throw new Error("evil-envFile-getter"); } });` Drive: `const gen = run("ralph", opts); await expect(gen.throw(new Error("my-err"))).rejects.toThrow("my-err");` Assert: (a) the consumer-supplied `"my-err"` surfaces (not `"evil-envFile-getter"`), (b) no child spawned, (c) no `loopx-*` tmpdir created, and (d) stderr does not surface the `"evil-envFile-getter"` error. *(Spec 9.1, 9.5)*
+- **T-API-69m**: `.throw()` as first interaction suppresses a throwing `options.maxIterations` getter. Companion to T-API-68n on the `.throw()` surface. Construct: `const opts = {}; Object.defineProperty(opts, "maxIterations", { enumerable: true, get() { throw new Error("evil-maxIterations-getter"); } });` Drive: `const gen = run("ralph", opts); await expect(gen.throw(new Error("my-err"))).rejects.toThrow("my-err");` Assert: (a) the consumer-supplied `"my-err"` surfaces (not `"evil-maxIterations-getter"`), (b) no child spawned, (c) no `loopx-*` tmpdir created, and (d) stderr does not surface the `"evil-maxIterations-getter"` error. Together with T-API-69e / T-API-69j / T-API-69k / T-API-69l, this completes throwing-getter coverage for every pinned `RunOptions` field — `signal`, `cwd`, `envFile`, `maxIterations`, `env` — under the `.throw()` carve-out, mirroring T-API-68k / T-API-68l / T-API-68m / T-API-68n / T-API-68h on the `.return()` surface. *(Spec 9.1, 9.5)*
+- **T-API-69n**: `.throw()` as first interaction suppresses an **unreadable global env file** failure. Companion to T-API-68o on the `.throw()` surface. Set up an isolated `XDG_CONFIG_HOME` with `loopx/env` written and `chmod 000`'d (the same fixture as T-API-68o / T-API-65r / T-TMP-12-global-env-unreadable). A valid `.loopx/ralph/index.sh`. Drive: `const gen = run("ralph"); await expect(gen.throw(new Error("my-err"))).rejects.toThrow("my-err");` Assert: (a) the consumer-supplied `"my-err"` surfaces (not the global-env-file-read error), (b) no child spawned, (c) no `loopx-*` tmpdir created, and (d) stderr does not surface the global-env-file-read error. Together with T-API-68o (`.return()` carve-out for the same failure mode), T-API-65r (abort-precedence), and T-SIG-30 (CLI signal-wins), this closes the global-env-unreadable sub-path on the `.throw()` carve-out surface. **Conditional on `process.getuid() !== 0`.** *(Spec 9.1, 8.1, 7.1)*
+- **T-API-69o**: `.throw()` as first interaction suppresses **local env-file parser warnings**. `.throw()` counterpart to T-API-68p. SPEC 9.1's "no pre-iteration step runs" clause must apply on the `.throw()` surface as well: the consumer's error surfaces per standard async-generator semantics and the env-file parse step never runs, so no SPEC 8.1 invalid-key warning fires. Set up: a project root with a valid `.loopx/ralph/index.sh`. Write a local env file (e.g., `<test-dir>/local.env`) with content `1BAD=val\nOK=fine\n` (the `1BAD` line is the SPEC 8.1 invalid-key warning trigger). Drive: `const gen = run("ralph", { envFile: "<test-dir>/local.env" }); await expect(gen.throw(new Error("my-err"))).rejects.toThrow("my-err");` Assert: (a) the consumer-supplied `"my-err"` surfaces (not any env-file load or parse error), (b) no child spawned, (c) no `loopx-*` tmpdir created, and (d) **stderr does not contain the SPEC 8.1 invalid-key parser warning for `1BAD`** — the env-file parse step never ran. A buggy implementation that ran the env-file parse step before checking whether the consumer had already invoked `.throw()` would fail (d). Together with T-API-68p (`.return()` counterpart) and T-API-69a (missing-file failure on `.throw()`), this closes the local env-file warning-suppression coverage across both consumer-driven first-interaction surfaces. *(Spec 9.1, 8.1, 8.2, 7.1)*
+- **T-API-69p**: `.throw()` as first interaction suppresses **global env-file parser warnings**. `.throw()` counterpart to T-API-68q. Set up: an isolated `XDG_CONFIG_HOME` (e.g., `<test-dir>/xdg-config`) with `loopx/env` written and containing `1BAD=val\nOK=fine\n`; the `XDG_CONFIG_HOME` is injected into loopx's inherited environment (same injection pattern as T-API-68q / T-API-68o / T-TMP-12-global-env-unreadable). A valid `.loopx/ralph/index.sh`. Drive: `const gen = run("ralph"); await expect(gen.throw(new Error("my-err"))).rejects.toThrow("my-err");` Assert: (a) the consumer-supplied `"my-err"` surfaces, (b) no child spawned, (c) no `loopx-*` tmpdir created, and (d) **stderr does not contain the SPEC 8.1 invalid-key parser warning for `1BAD`** — the global-env-file parse step never ran. Together with T-API-68q (`.return()` counterpart) and T-API-69n (global-env-unreadable failure on `.throw()`), this closes the global env-file warning-suppression branch of SPEC 9.1's "no pre-iteration step runs" clause across both consumer-driven first-interaction surfaces. *(Spec 9.1, 8.1, 7.1)*
+- **T-API-69q**: `.throw()` as first interaction suppresses **workflow `package.json` warnings** from the starting-workflow version check. `.throw()` counterpart to T-API-68r. **Parameterize over the four SPEC 3.2 warning branches** (unsatisfied range, invalid JSON, invalid semver range, unreadable `package.json`) using the same per-variant fixtures as T-API-68r. For each variant, drive: `const gen = run("ralph"); await expect(gen.throw(new Error("my-err"))).rejects.toThrow("my-err");` Assert (per variant): (a) the consumer-supplied `"my-err"` surfaces (not any version-check or `package.json`-related error or warning chained onto it), (b) no child spawned, (c) no `loopx-*` tmpdir created, and (d) **stderr does not contain the `package.json` warning text** for that variant. Variant (iv) (unreadable) is **conditional on `process.getuid() !== 0`**. Together with T-API-68r (`.return()` counterpart), this closes the workflow `package.json` warning-suppression branch of SPEC 9.1's "no pre-iteration step runs" clause across both consumer-driven first-interaction surfaces and across all four SPEC 3.2 `package.json` failure-mode warning branches. *(Spec 9.1, 7.1, 3.2)*
+- **T-API-69h**: `.throw()` as first interaction suppresses **the full enumerated invalid `maxIterations` set plus a representative selection of remaining option-snapshot failures**. SPEC 9.1's pre-first-`next()` carve-out enumerates "captured option-snapshot errors (invalid `options` values, invalid `options.signal`, non-string `options.cwd` / `options.envFile`, invalid `options.maxIterations`, invalid `options.env` shape, throwing option-field getters, throwing `options.env` enumerable getters or proxy traps)" among the suppressed pre-iteration errors. T-API-69e covers the throwing `options.env` getter case; this test extends coverage to (i) the **full enumerated invalid `maxIterations` set** (every value treated as invalid in the validation matrix at T-API-22 etc., parameterized exhaustively) and (ii) a **representative selection** of the remaining option-snapshot families (invalid `options` shape, invalid `options.signal`, invalid `cwd` / `envFile` types, representative invalid `env` shape and entry value, throwing `env` entry getter, throwing `env` proxy traps) — in a single parameterized test, mirroring T-API-68i but for the `.throw()` surface. The full invalid `env` shape/value matrix (every shape from T-API-53–53d and every entry-value variant from T-API-54–54c) is intentionally **not** exhaustively re-parameterized here — those validation paths converge on a single "captured option-snapshot error" code path that the carve-out must suppress, and the representative sample is sufficient to detect a buggy implementation that bypassed the carve-out on the option-snapshot category; T-API-53–55 and T-API-55a–55d carry the exhaustive env-shape coverage without carve-out pinning. **Target-resolution failures are not parameterized here** — they are already covered by T-API-69g, which keeps the parameterized target-resolution test separate from the option-snapshot test on the `.throw()` surface. **Parameterize over each variant**, set up the relevant fixture, drive `const gen = run("ralph", <opts>); await expect(gen.throw(new Error("my-err"))).rejects.toThrow("my-err");` and assert per variant: (a) the consumer-supplied `"my-err"` surfaces — not the configured option-snapshot error, (b) no child spawned (no marker file written), (c) no `loopx-*` tmpdir is created (assertion is scoped to the test-isolated tmpdir parent per the section 4.7 tmpdir-block preface), and (d) stderr does not surface the configured option-snapshot error. **Variants:** **(i) invalid `options` shape — `null`** (`run("ralph", null as any)`); **(ii) invalid `options` shape — array** (`run("ralph", [] as any)`); **(iii) invalid `options` shape — function** (`run("ralph", (() => {}) as any)`); **(iv) invalid `options` shape — primitive number** (`run("ralph", 42 as any)`); **(v) invalid `options.signal` — non-`AbortSignal`-shaped value** (`run("ralph", { signal: "not-a-signal" as any })`); **(vi) non-string `options.cwd`** (`run("ralph", { cwd: 42 as any })`); **(vii) non-string `options.envFile`** (`run("ralph", { envFile: 42 as any })`); **(viii) invalid `options.maxIterations: -1`** (`run("ralph", { maxIterations: -1 })`); **(ix) invalid `options.maxIterations: 1.5`** (`run("ralph", { maxIterations: 1.5 })` — non-integer); **(x) invalid `options.maxIterations: NaN`** (`run("ralph", { maxIterations: NaN })`); **(xi) invalid `options.maxIterations: Infinity`** (`run("ralph", { maxIterations: Infinity })` — non-finite); **(xii) invalid `options.maxIterations: null as any`** (`run("ralph", { maxIterations: null as any })` — null is not a finite non-negative integer); **(xiii) invalid `options.maxIterations: "1" as any`** (`run("ralph", { maxIterations: "1" as any })` — string value rejected at the type-shape gate, distinct from the numeric-range gates of (viii)–(xii)); **(xiv) representative invalid `options.env` shape — array** (`run("ralph", { env: [] as any })` — representative sample of the SPEC 9.5 / T-API-53–53d shape-validation matrix); **(xv) representative invalid `options.env` non-string entry value** (`run("ralph", { env: { KEY: 42 as any } })` — representative sample of the SPEC 9.5 / T-API-54–54c entry-value-validation matrix); **(xvi) throwing `options.env` proxy `ownKeys` trap** — construct `const env = new Proxy({}, { ownKeys() { throw new Error("ownKeys-trap-boom"); } });` and call `run("ralph", { env })`; **(xvii) invalid target syntax** — call `run("a:b:c")` (three-segment target violates the `<workflow>[:<script>]` grammar; this exercises the target-syntax-validation branch of SPEC 9.1's carve-out, distinct from T-API-69's `undefined`-target argument-validation case and from T-API-69g's post-syntax target-resolution branches); **(xviii) throwing enumerable getter inside `options.env`** — construct `const env = {}; Object.defineProperty(env, "KEY", { enumerable: true, get() { throw new Error("env-entry-getter-boom"); } });` and call `run("ralph", { env })` (this exercises the "throwing enumerable getters inside `options.env`" sub-clause of SPEC 9.1's carve-out, distinct from variant (xvi)'s proxy `ownKeys` trap and from T-API-69e's throwing getter on the **options object's `env` property** itself); **(xix) throwing `options.env` proxy `getOwnPropertyDescriptor` trap** (observational on the trap-invocation axis) — construct `const env = new Proxy({ A: "a" }, { getOwnPropertyDescriptor() { throw new Error("descriptor-trap-boom"); } });` and call `run("ralph", { env })`. As with T-API-68i variant (xxi), SPEC does not require the descriptor trap to be invoked during the snapshot (see T-API-62f2). This variant exercises the carve-out only on implementations that invoke the descriptor trap and capture its throw — for those implementations, the captured exception must be suppressed and the consumer-supplied error must surface. On implementations that do not invoke the descriptor trap, no snapshot exception is captured, and the consumer-supplied error surfaces as it would on any other non-throwing-snapshot path; **(xx) throwing `options.env` proxy `get` trap** — construct `const env = new Proxy({ A: "a" }, { ownKeys() { return ["A"]; }, getOwnPropertyDescriptor(t, key) { return { enumerable: true, configurable: true, value: undefined, writable: true }; }, get() { throw new Error("get-trap-boom"); } });` and call `run("ralph", { env })` (extends proxy-trap suppression coverage to the value-read `get` trap; the `get` trap is necessarily invoked when loopx reads each entry's value, so this variant is a strict suppression pin — the captured snapshot exception must be suppressed and the consumer-supplied error must surface). Variant (xix) is observational on the descriptor-trap-invocation axis; variant (xx) is a strict suppression pin. For each variant, all four assertions (a)–(d) hold and the consumer-supplied `"my-err"` is the surfaced rejection reason — not any captured snapshot error. A buggy implementation that surfaced the captured snapshot error (or any combined error) instead of the consumer-supplied error would fail (a). An implementation that performed tmpdir creation under the carve-out before settling would fail (c). Together with T-API-69 (target-argument validation), T-API-69a (env-file), T-API-69b (pre-aborted signal), T-API-69c (no-tmpdir negative observation), T-API-69d (tmpdir-creation), T-API-69e (throwing getter on `options.env` property), T-API-69f (discovery), and T-API-69g (target-resolution), this test completes the `.throw()` carve-out coverage across the SPEC 9.1 enumeration with exhaustive `maxIterations` coverage and representative env-shape coverage. *(Spec 9.1, 9.5, 7.4)*
+- **T-API-70**: `runPromise` has no carve-out. `runPromise(undefined as any, { envFile: "nonexistent.env" })` always rejects; there is no `.return()` / `.throw()` path on a promise. Explicitly documents Spec 9.1 "This carve-out applies only to `run()`; `runPromise()` has no equivalent." The test is a pair of "both rejections happen" assertions on `runPromise` for each invalid input, matching T-API-68a/68b/68c/68d. *(Spec 9.2)*
+
+##### Snapshot Timing (Inherited Env)
+
+- **T-API-71**: `run()` inherited-env snapshot is lazy (captured at first `next()`). Set `process.env.MYVAR=A`. `const gen = run("ralph", { maxIterations: 1 });` — no snapshot yet. Set `process.env.MYVAR=B` **before** `gen.next()`. Await `.next()`. Script observes `MYVAR`. Assert marker shows `"B"` — the mutation between `run()` returning and first `next()` is observed. *(Spec 9.1, 8.1)*
+- **T-API-71a**: `run()` inherited-env snapshot is frozen at first `next()` (later mutations not observed). Set `process.env.MYVAR=A`. `const gen = run("ralph", { maxIterations: 2 }); await gen.next();` (first iteration captures `"A"`). Set `process.env.MYVAR=B`. `await gen.next();` (second iteration). Assert both iterations saw `"A"`. *(Spec 9.1, 8.1)*
+- **T-API-72**: `runPromise()` inherited-env snapshot is eager (captured at call site). Set `process.env.MYVAR=A`. `const p = runPromise("ralph", { maxIterations: 1 });` — snapshot taken synchronously. Set `process.env.MYVAR=B`. Await `p`. Script observes `MYVAR`. Assert marker shows `"A"` — mutation after return did not propagate. *(Spec 9.2, 8.1)*
+- **T-API-72a**: `runPromise()` inherited-env snapshot is **reused across iterations** — the eager snapshot taken at the call site applies to every spawn in the run, not just the first. T-API-72 proves the snapshot is captured synchronously before `runPromise()` returns for a single-iteration run, but it does not prove the snapshot is reused for the *second* spawn in a multi-iteration run. A buggy implementation that captured the inherited env eagerly at the call site (passing T-API-72) but re-read `process.env` between iterations (re-snapshotting before each spawn) would propagate mid-run mutations to later iterations and silently violate SPEC 8.1's "inherited `process.env` is snapshotted once per run ... mutations between spawns do not propagate". This test pins down the cross-iteration reuse contract on the `runPromise()` surface. **Setup.** Set `process.env.MYVAR = "A"`. Compute a unique release-file path outside any tmpdir (e.g., `<test-tmp>/release-<uuid>.flag`) and an external observation-marker path per-iteration (so observations survive cleanup). `.loopx/ralph/index.sh` reads `OBSERVED_MARKER_PREFIX` and `RELEASE_FILE` from its environment, observes `MYVAR` via `observe-env` into `${OBSERVED_MARKER_PREFIX}-iter-${ITER}.json` (where `ITER` is derived from a counter file the script maintains on disk under the marker prefix — first iteration writes "1", second writes "2"), then on the **first** iteration only, writes `"ready"` to a coordination marker and **blocks on a sentinel** by polling for `RELEASE_FILE` to exist (e.g., `until [ -e "$RELEASE_FILE" ]; do sleep 0.05; done`) before exiting cleanly with `{}` (no `goto`, no `stop` — the loop resets to the starting target for iteration 2). On the second iteration, the script observes `MYVAR`, writes its marker, and emits `{"stop":true}` to terminate. **Drive.** Pass the per-run paths via `RunOptions.env` (`{ env: { OBSERVED_MARKER_PREFIX: "<abs-path>", RELEASE_FILE: "<abs-path>" } }` — note: this puts the *paths* in `RunOptions.env`, not the test variable `MYVAR`, which must come from inherited env to exercise the inherited-env snapshot path). Call `const p = runPromise("ralph", { maxIterations: 2, env: { OBSERVED_MARKER_PREFIX, RELEASE_FILE } })`. The harness then waits (via the iter-1 marker file's appearance) for the first iteration to complete its observation and reach the sentinel-poll, **mutates** `process.env.MYVAR = "B"`, and creates the release file (e.g., `fs.writeFileSync(RELEASE_FILE, "")`) so the first iteration's blocking-poll exits and the script terminates. The second iteration spawns; the loop reset re-runs `ralph:index`. Await `p`. **Assert.** (a) the promise resolves (no rejection), (b) the iter-1 marker records `MYVAR === "A"` (the eager snapshot was used for the first spawn), (c) the iter-2 marker records `MYVAR === "A"` — **the same snapshot was reused for the second spawn even though `process.env.MYVAR` was mutated to `"B"` between iterations** — proving SPEC 8.1's "snapshotted once per run ... mutations between spawns do not propagate" rule on the `runPromise()` surface, and (d) `process.env.MYVAR === "B"` in the harness after the promise settles (the harness's mutation took effect in its own process; the assertion (c) is solely about whether that mutation propagated to the spawned scripts). The complementary `run()`-surface test for cross-iteration snapshot reuse is T-API-71a (set `MYVAR=A`, drive `gen.next()` twice with `MYVAR=B` between, assert both iterations observed `"A"`); T-API-71a relies on the consumer to drive iterations via successive `next()` calls, but `runPromise()` has no such consumer-driven boundary — the harness must use a release-file sentinel to synchronize the mid-run mutation with iteration boundaries. *(Spec 9.2, 8.1)*
+
+##### Global Env File Resolution Snapshot Timing (`XDG_CONFIG_HOME` / `HOME`)
+
+SPEC 8.1 says global env-file path resolution (`$XDG_CONFIG_HOME/loopx/env`, or `$HOME/.config/loopx/env` fallback) reads `XDG_CONFIG_HOME` / `HOME` from the inherited environment on the **same schedule as the inherited-env snapshot**: lazy under `run()` (captured at first `next()`), eager under `runPromise()` (captured at the call site). T-API-71 / T-API-71a / T-API-72 cover inherited-env snapshot timing but do not exercise the `XDG_CONFIG_HOME` / `HOME` resolution path specifically — a buggy implementation could snapshot `process.env` lazily but read `XDG_CONFIG_HOME` / `HOME` eagerly (or vice versa).
+
+- **T-API-73**: `run()` — `XDG_CONFIG_HOME` resolution is lazy (captured at first `next()`). Create two isolated config directories, `/tmp/xdg-A/loopx/env` (with `MARKER=from-A`) and `/tmp/xdg-B/loopx/env` (with `MARKER=from-B`). Set `process.env.XDG_CONFIG_HOME = "/tmp/xdg-A"`. Call `const gen = run("ralph", { maxIterations: 1 })`. Set `process.env.XDG_CONFIG_HOME = "/tmp/xdg-B"` **before** `await gen.next()`. Script observes `MARKER`. Assert the marker shows `"from-B"` — the mutation between `run()` returning and first `next()` redirected global env-file lookup. A buggy implementation that read `XDG_CONFIG_HOME` eagerly would show `"from-A"`. *(Spec 9.1, 8.1)*
+- **T-API-73a**: `runPromise()` — `XDG_CONFIG_HOME` resolution is eager (captured at call site). Same two-config setup as T-API-73. Set `process.env.XDG_CONFIG_HOME = "/tmp/xdg-A"`. Call `const p = runPromise("ralph", { maxIterations: 1 })` — snapshot taken synchronously. Set `process.env.XDG_CONFIG_HOME = "/tmp/xdg-B"`. Await `p`. Script observes `MARKER`. Assert the marker shows `"from-A"` — mutation after return did not redirect global env-file lookup. *(Spec 9.2, 8.1)*
+- **T-API-73b**: `run()` — `HOME` fallback resolution is lazy (captured at first `next()`). Unset `XDG_CONFIG_HOME` in `process.env` so loopx falls back to `$HOME/.config/loopx/env`. Create two isolated home directories, `/tmp/home-A/.config/loopx/env` (with `MARKER=from-A`) and `/tmp/home-B/.config/loopx/env` (with `MARKER=from-B`). Set `process.env.HOME = "/tmp/home-A"`. Call `const gen = run("ralph", { maxIterations: 1 })`. Set `process.env.HOME = "/tmp/home-B"` before `await gen.next()`. Script observes `MARKER`. Assert the marker shows `"from-B"` — the `HOME` mutation between `run()` returning and first `next()` redirected global env-file lookup via the fallback path. *(Spec 9.1, 8.1)*
+- **T-API-73c**: `runPromise()` — `HOME` fallback resolution is eager (captured at call site). Same two-home setup as T-API-73b. Set `process.env.HOME = "/tmp/home-A"`, unset `XDG_CONFIG_HOME`. Call `const p = runPromise("ralph", { maxIterations: 1 })`. Set `process.env.HOME = "/tmp/home-B"`. Await `p`. Script observes `MARKER`. Assert the marker shows `"from-A"` — mutation after return did not affect the fallback path. *(Spec 9.2, 8.1)*
+
 ### 4.10 Install Command
 
-**Spec refs:** 10.1–10.9
+**Spec refs:** 10.1–10.10
 
 All install tests use local servers (HTTP, file:// git repos). No network access.
 
+**Auto-install-awareness rule for install tests.** SPEC 10.10 means any successful install of a workflow with a top-level `package.json` will run `npm install` by default and synthesize `.gitignore`. Tests outside the auto-install block (`Auto-install of Workflow Dependencies`, T-INST-110+) often install workflows whose sources happen to contain a top-level `package.json` (because version-checking, classification, or atomicity scenarios commonly use `package.json` to declare a `loopx` range or to populate workflow content). A conforming implementation will invoke real or fake `npm` for those workflows, which can make non-auto-install tests flaky, slow, or wrong (especially when the workflow declares an unsatisfied `loopx` range, or when no fake-`npm` shim is installed and the test harness has no real `npm` on a scrubbed `PATH`).
+
+**Rule (suite-wide).** Unless a test is explicitly exercising SPEC 10.10 auto-install behavior, **any test in this document — anywhere, in any section — that invokes `loopx install`** against a source whose selected workflows are actually committed and contain a top-level `package.json` must either pass `--no-install` or wrap the command with `withFakeNpm` (section 2.3). The rule is **not scoped to section 4.10**: it also covers install invocations in section 4.12 (CLI delegation × install-time version checking — e.g., T-DEL-25), section 4.13 (workflow-level version checking install-time variants — the T-VER-12*, T-VER-13*, T-VER-15*, T-VER-17 family), and any future section that introduces an `loopx install` invocation. The rule applies only to tests that reach the post-commit auto-install pass; tests where install fails before any commit (e.g., blocking preflight failures like a version-mismatch refusal — see T-INST-72 / T-INST-72a) have no auto-install candidate and do not need `--no-install`, though they may pass it harmlessly. Prefer `--no-install` for classification, copy, collision, atomicity, delegation, and version-check tests where auto-install is incidental. Tests in the T-INST-110 through T-INST-120b auto-install block intentionally omit `--no-install` and use `withFakeNpm` because auto-install is the contract under test. Specifically:
+
+- Classification and copy tests with workflow-internal `package.json`: pass `--no-install` (e.g., T-INST-50, T-INST-54a, T-INST-83a).
+- Collision tests using sources that include a `package.json` (e.g., T-INST-67/T-INST-67a/T-INST-70-family when the source workflow has one): pass `--no-install`.
+- Install atomicity tests with workflow-internal `package.json` (e.g., T-INST-80): pass `--no-install`.
+- Install-time `package.json` warning-cardinality tests with committed workflows (T-INST-80d, T-INST-80e, T-INST-80f): pass `--no-install`. These tests live in the install-atomicity block by ID range but their contract is the install-time `package.json` warning behavior described in SPEC 3.2 / 10.6 — "once per affected workflow" — for unreadable, invalid-semver, and invalid-JSON `package.json` content respectively. Each test installs two workflows that successfully commit, and each workflow has a top-level `package.json` that would otherwise be considered for the post-commit auto-install pass; the auto-install pass is incidental and must not run in these tests.
+- Install-time version-check tests where the test's selected workflows actually commit (e.g., T-INST-73/T-INST-73a, T-INST-60j, T-INST-74/T-INST-74a, T-INST-75/T-INST-75a, T-INST-76/T-INST-76a, T-INST-60q/T-INST-60r/T-INST-60s — these install successfully despite warnings, or override version-mismatch via `-y`): pass `--no-install`. The test's purpose is the version-check / parse-warning behavior, not the auto-install pass; T-INST-120b separately covers the `-y`-overrides-version-mismatch × auto-install combination with `withFakeNpm`. **Blocking-preflight version-check tests** that reject install before any commit (e.g., T-INST-72, T-INST-72a, T-INST-60i — version-mismatch error, no `-y`): the rule does not apply because no commit means no auto-install candidate; passing `--no-install` is unnecessary (and the tests' bodies note this explicitly).
+- `-y` × version-mismatch tests where the auto-install-after-`-y` interaction is **not** the contract under test (e.g., T-INST-60j): pass `--no-install`.
+- **Cross-section install tests outside section 4.10.** The same `--no-install`-or-`withFakeNpm` requirement applies. Concretely: **T-DEL-25** (section 4.12 — delegation × install-time version checking; the source workflow declares a satisfied `loopx` range in its `package.json`, which would otherwise drive the post-commit auto-install pass) must pass `--no-install`. The install-time version-check tests in section 4.13 — **T-VER-12** (satisfied-range install sub-case), **T-VER-12a / 12b / 12c** (where auto-install is incidental to the version-check / `package.json`-shape behavior), **T-VER-13 / 13a / 13b / 13d** (selective `optionalDependencies` / `peerDependencies` / non-`loopx` field cases that install successfully), the `-y` success sub-cases inside **T-VER-13c** and **T-VER-15a** (`-y` unblocks the mismatch and the post-commit auto-install pass would otherwise run), **T-VER-15b** (satisfied-range `devDependencies`-only install), and **T-VER-17** (no `loopx` declared, install succeeds) — all must pass `--no-install` because their contract is the version-check / `package.json`-shape behavior, not auto-install. **T-VER-15c remains as-is** with `withFakeNpm` because that test explicitly asserts the SPEC 10.10 malformed-`package.json` auto-install-skip contract (the fake-npm shim's empty log is the assertion surface for "auto-install was skipped"). **T-INST-120b** also remains as-is for the same reason it always has — it intentionally uses `withFakeNpm` to assert the `-y`-then-auto-install combination. The principle: any `loopx install` outside the `withFakeNpm`-wrapped tests in 4.10 / 4.12 / 4.13 must use `--no-install` whenever the source has a top-level `package.json`, because conforming SPEC 10.10 auto-install behavior would otherwise spawn a real or fake `npm` and make the test flaky, slow, or PATH-dependent.
+
+T-INST-120b remains the canonical "`-y` unblocks preflight, then auto-install runs fresh" test and intentionally uses `withFakeNpm` (no `--no-install`). Tests that use `withFakeNpm` already inhibit real-npm flakiness; they do not also need `--no-install`.
+
+**Affected existing tests.** The rule applies unconditionally to every test in this document that invokes `loopx install` and whose source has a top-level `package.json`. Where the test's source description above already lists a workflow `package.json`, treat that test as passing `--no-install` even if the test text predates this rule. This includes **T-DEL-25** in section 4.12 and the install-time version-check tests in section 4.13 enumerated in the bullet above. The auto-install block (T-INST-110 through T-INST-120b) and **T-VER-15c** use `withFakeNpm` and do not pass `--no-install`.
+
 #### Source Detection
 
 - **T-INST-01**: `loopx install myorg/my-workflow` is treated as a git source (github shorthand). Verify by using `withGitURLRewrite` to redirect to a local bare repo, and asserting workflows are installed into `.loopx/`. *(Spec 10.1)*
@@ -1332,6 +2689,7 @@ All install tests use local servers (HTTP, file:// git repos). No network access
 - **T-INST-03**: `loopx install https://gitlab.com/org/repo` → treated as git. *(Spec 10.1)*
 - **T-INST-04**: `loopx install https://bitbucket.org/org/repo` → treated as git. *(Spec 10.1)*
 - **T-INST-05**: `loopx install https://example.com/repo.git` → treated as git (.git suffix). *(Spec 10.1)*
+- **T-INST-05a**: `loopx install https://example.com/repo.git/` (trailing slash on a non-known-host `.git` URL) → rejected as an unsupported source. SPEC 10.1 rule 2 explicitly permits an optional trailing slash on the `/<owner>/<repo>.git` pathname for **known-host** URLs (`github.com`, `gitlab.com`, `bitbucket.org` — covered for the trailing-slash variant by T-INST-08h). SPEC 10.1 rule 3 says "Any **other** URL ending in `.git` is treated as a git source" — a URL whose pathname ends in `.git/` (with trailing slash) does **not** end in `.git` per the literal text of rule 3, so the generic non-known-host fallback does not classify it as git. The URL also does not end in `.tar.gz` / `.tgz`, so rule 4 (tarball) does not match. The URL therefore falls through to rule 5 (rejection). T-INST-05 covers the no-trailing-slash form on a non-known-host (accepted by rule 3); T-INST-08h covers the trailing-slash form on a **known** host (accepted by rule 2 with the explicit optional-trailing-slash clause). This test pins down the asymmetry between rule 2 (explicit trailing-slash allowance) and rule 3 (no trailing-slash allowance), which would otherwise be discoverable only by inspecting the parser. Run `loopx install https://example.com/repo.git/`. Assert: (a) exit code 1, (b) stderr references the source-detection rejection (not a downstream git/tarball failure — the rejection fires at source classification, before any network operation), and (c) no `git clone` invocation is recorded against `https://example.com/repo.git/` (verifiable via `withFakeGit` showing zero clone invocations for this URL, or by relying on the pre-network exit-1 surface). A permissive implementation that normalized away a trailing slash before applying rule 3 would wrongly accept this URL — this test catches that relaxation. *(Spec 10.1)*
 - **T-INST-06**: `loopx install http://localhost:PORT/pkg.tar.gz` → treated as tarball. *(Spec 10.1)*
 - **T-INST-07**: `loopx install http://localhost:PORT/pkg.tgz` → treated as tarball. *(Spec 10.1)*
 - **T-INST-08**: `loopx install http://localhost:PORT/script.ts` → rejected (single-file URL install is not supported). Error, exit code 1. *(Spec 10.1)*
@@ -1340,6 +2698,14 @@ All install tests use local servers (HTTP, file:// git repos). No network access
 - **T-INST-08d**: `loopx install http://localhost:PORT/pkg.tar.gz?token=abc` → treated as tarball. *(Spec 10.1)*
 - **T-INST-08e**: `loopx install http://localhost:PORT/some-file.js` → rejected. Any URL that is not git or tarball is an error. *(Spec 10.1)*
 - **T-INST-08f**: `loopx install https://github.com/org/repo/tree/main` → rejected. Known-host git detection only matches exact `/<owner>/<repo>` or `/<owner>/<repo>.git` paths. A URL with additional path segments (like `/tree/main`) is not treated as a git repo. Since it is also not a tarball URL, it is rejected with an error (exit code 1). *(Spec 10.1)*
+- **T-INST-08g**: `loopx install https://github.com/org/repo?x=1` → treated as git (known host, query string does not alter source classification). Per SPEC 10.1 rule 2, known-host git detection matches on the URL **pathname** and is unaffected by query string or fragment. **Assert classification and install behavior, not an exact clone URL spelling.** SPEC 10.1 pins down *classification* (the URL is a git source), but does **not** specify whether the query string (or fragment) is retained or stripped before the URL is passed to `git clone` — both normalized forms (preserving `?x=1` vs. stripping it) are SPEC-conforming. A buggy implementation that misclassified the query-bearing URL as a tarball or rejected it outright would fail; a conforming implementation that normalizes the URL differently than the test harness expects must still pass. To exercise this without over-pinning the clone-URL spelling, use `withFakeGit` (section 2.3) to capture loopx's actual `git clone` argv, and configure `withGitURLRewrite` to map **both** possible normalized forms (`https://github.com/org/repo` and `https://github.com/org/repo?x=1`) to the same local bare repo — this way loopx's choice of either normalization succeeds. Run `loopx install https://github.com/org/repo?x=1` and assert: (a) the source was classified as git (via the `withFakeGit` log showing a `git clone` invocation, not a tarball download), (b) the clone argv contains a URL whose pathname is `/org/repo` (the SPEC-pinned classification surface — query string / fragment presence is not asserted), (c) the workflow was installed into `.loopx/<repo>/`, and (d) exit code 0. Query-string counterpart to T-INST-02 (bare known-host URL). Together with T-INST-08c (trailing slash), this pins down that both of the "same-path" URL variants (`?…` and `/`) classify as git on a known host. *(Spec 10.1)*
+- **T-INST-08g2**: `loopx install https://github.com/org/repo#section` → treated as git (known host, fragment does not alter source classification). Per SPEC 10.1 rule 2, known-host git detection matches on the URL pathname and is unaffected by query string or fragment — the pathname `/org/repo` classifies as git regardless of what follows `#`. Fragment counterpart to T-INST-08g (query string). **Assert classification and install behavior, not an exact clone URL spelling**, for the same reason as T-INST-08g: SPEC 10.1 does not specify whether the fragment is retained or stripped before `git clone`. Use `withFakeGit` to capture loopx's `git clone` argv and configure `withGitURLRewrite` to map **both** possible normalized forms (`https://github.com/org/repo` and `https://github.com/org/repo#section`) to the same local bare repo. Run `loopx install https://github.com/org/repo#section` and assert: (a) the source was classified as git (via the `withFakeGit` log showing a `git clone` invocation), (b) the clone argv contains a URL whose pathname is `/org/repo` (the SPEC-pinned classification surface — fragment presence is not asserted), (c) the workflow was installed into `.loopx/<repo>/`, and (d) exit code 0. *(Spec 10.1)*
+- **T-INST-08h**: `loopx install https://github.com/org/repo.git/` → treated as git (known host, `.git` pathname with trailing slash). Per SPEC 10.1 rule 2, the pathname `/<owner>/<repo>.git` with optional trailing slash is the explicit `.git`-form of the known-host rule. T-INST-05 covers the generic `.git`-suffix rule (rule 3), T-INST-02 covers the no-`.git` known-host form, and T-INST-08c covers the trailing-slash variant without `.git`; this test closes the `.git/`-with-trailing-slash variant on a known host. *(Spec 10.1)*
+- **T-INST-08i**: `loopx install org/repo/extra` → rejected with an error. The `org/repo` shorthand matches only exactly one slash with no additional path segments; this input is not shorthand and is not a supported URL source. *(Spec 10.1)*
+- **T-INST-08j**: `loopx install org/repo/` → rejected with an error. SPEC 10.1 describes the `org/repo` shorthand as "exactly one slash and no extra path segments"; a trailing slash adds an empty-string path segment that does not match the single-slash shorthand shape. T-INST-08c covers the URL-form `https://github.com/org/repo/` (which *is* accepted because the known-host URL rule permits trailing slash), but shorthand and URL-form are distinct grammars — pinning trailing-slash acceptance for one does not constrain the other. T-INST-08i covers the `org/repo/<extra>` non-empty-extra-segment case; this test covers the `org/repo/` empty-extra-segment case. Assert: (a) exit code 1, and (b) stderr references the invalid source / shorthand rejection. *(Spec 10.1)*
+- **T-INST-08k**: `loopx install org//repo` → rejected with an error. The `org/repo` shorthand requires a single slash separating two non-empty segments; `org//repo` has two slashes (or, equivalently, an empty middle segment). A permissive implementation that split on `/` and ignored empty segments would wrongly accept this as `org/repo` — this test catches that relaxation. Assert: (a) exit code 1, (b) stderr references the invalid source / shorthand rejection, and (c) no git clone attempt is made against a `github.com/org/repo` URL (verifiable via `withFakeGit` log being empty of clone invocations for the rewritten URL, or by simply relying on the fact that exit 1 is raised at source detection before any network/git operation). *(Spec 10.1)*
+- **T-INST-08l**: `loopx install https://github.com/org` (one path segment only) → rejected. SPEC 10.1 rule 2 requires the URL pathname to be exactly `/<owner>/<repo>` or `/<owner>/<repo>.git` (optionally trailing slash). A pathname with a single segment `/org` does not match either form. Existing T-INST-08f covers the "extra path segments after `/<owner>/<repo>`" rejection (`/org/repo/tree/main`); this test covers the symmetric "missing `<repo>` segment" rejection. A permissive implementation that accepted any github.com URL without enforcing the `/<owner>/<repo>` shape would wrongly try to clone `https://github.com/org` and fail later in the pipeline (or worse, succeed against an unintended target). Run `loopx install https://github.com/org`. Assert: (a) exit code 1, (b) stderr references the source-detection / unsupported-URL rejection (not a generic clone failure — the rejection must fire at source classification, before any git operation), and (c) no `git clone` attempt is made (verifiable via `withFakeGit` showing zero clone invocations, or by relying on the pre-network exit-1 surface). *(Spec 10.1)*
+- **T-INST-08m**: `loopx install https://github.com/org/repo.git/extra` → rejected. SPEC 10.1 rule 2 specifies the pathname must be exactly `/<owner>/<repo>` or `/<owner>/<repo>.git` (optionally trailing slash). A pathname with **additional** path segments after `.git` (e.g., `/org/repo.git/extra`) does not match — it is neither a known-host git URL (rule 2 fails) nor classifiable as a tarball (rule 4 requires `.tar.gz`/`.tgz`). T-INST-08f covers the no-`.git` extra-segments rejection (`/org/repo/tree/main`); this test covers the `.git`-with-extra-segments rejection — a distinct branch of the parser since the `.git` suffix could be a tempting normalization target. A permissive implementation that stripped `.git` and then accepted the resulting pathname, or that strip-suffixed `.git` and then ignored trailing segments, would wrongly accept this URL. Run `loopx install https://github.com/org/repo.git/extra`. Assert: (a) exit code 1, (b) stderr references the source-detection rejection (not a downstream git failure), and (c) no `git clone` attempt is made. Together with T-INST-08l (missing-segment rejection), T-INST-08f (extra-segments-without-`.git` rejection), and T-INST-08h (`.git/`-with-trailing-slash acceptance), these four tests pin down the four shapes the known-host parser must handle: accept exact `/<owner>/<repo>` (T-INST-02 / T-INST-08c), accept `/<owner>/<repo>.git` (T-INST-08h covers trailing-slash variant; T-INST-05 covers generic `.git` rule), reject extra segments (T-INST-08f), reject `.git`-then-extra-segments (this test), and reject single-segment paths (T-INST-08l). *(Spec 10.1)*
 
 #### Install CLI Parsing
 
@@ -1347,9 +2713,10 @@ All install tests use local servers (HTTP, file:// git repos). No network access
 - **T-INST-40a**: `loopx install -w ralph` with no source → usage error, exit code 1. The `-w` flag does not substitute for the required `<source>` argument. *(Spec 4.2, 10)*
 - **T-INST-40b**: `loopx install --workflow ralph` with no source → usage error, exit code 1. Same as T-INST-40a using the long-form `--workflow` flag. *(Spec 4.2, 10)*
 - **T-INST-40c**: `loopx install -y` with no source → usage error, exit code 1. The `-y` flag does not substitute for the required `<source>` argument. *(Spec 4.2, 10)*
-- **T-INST-40d**: `loopx install <source1> <source2>` → usage error, exit code 1. The install grammar accepts exactly one positional source argument; extra positionals are rejected. *(Spec 4.2, 10)*
-- **T-INST-40e**: `loopx install -w ralph <source1> <source2>` → usage error, exit code 1. Extra positionals are rejected even when combined with the `-w` flag. *(Spec 4.2, 10)*
-- **T-INST-41**: `loopx install -h` → install help, exit 0. Source not required. Assert that the help text explicitly lists: (a) `-w` / `--workflow` option with description, (b) `-y` option with description, (c) supported source types (git repos, tarballs, `org/repo` shorthand), and (d) does NOT mention single-file URL install as a supported source type — single-file URL install was removed (ADR-0003) and the help text must not advertise it. *(Spec 4.2, 10.1, 11.3)*
+- **T-INST-40d**: `loopx install <source1> <source2>` → usage error, exit code 1. The install grammar accepts exactly one positional source argument; extra positionals are rejected. SPEC 4.3 / 10 require exactly one `<source>` positional ("`<source>` is required"), and SPEC 12's usage-error contract for parser-level surface errors makes "extra positionals on install" a direct usage error. *(Spec 4.2, 10, 12)*
+- **T-INST-40e**: `loopx install -w ralph <source1> <source2>` → usage error, exit code 1. Extra positionals are rejected even when combined with the `-w` flag. Same grammar reasoning as T-INST-40d applied with `-w` present. *(Spec 4.2, 10, 12)*
+- **T-INST-40f**: `loopx install --no-install` with no source → usage error, exit code 1. `--no-install` does not substitute for the required `<source>` argument. *(Spec 4.2, 10)*
+- **T-INST-41**: `loopx install -h` → install help, exit 0. Source not required. Assert that the help text explicitly lists: (a) `-w` / `--workflow` option with description, (b) `-y` option with description, (c) **`--no-install` option with description** (per SPEC 4.2 / 11.3 — suppresses auto-install of workflow dependencies per Spec 10.10), (d) supported source types (git repos, tarballs, `org/repo` shorthand), (e) does NOT mention single-file URL install as a supported source type — single-file URL install was removed (ADR-0003) and the help text must not advertise it, and (f) **does NOT advertise any short alias for `--no-install`** — SPEC 4.2 explicitly says `--no-install` has "No short form". The help text's option line for `--no-install` (and any synopsis / usage block listing install-scoped flags) must not list `-n`, `-N`, `-i`, `-I`, or any other single-character form alongside `--no-install`. A buggy implementation that introduced a hidden `-n` / `-i` alias and advertised it in the help text would fail (f); the parser side is pinned separately by T-INST-44f. *(Spec 4.2, 10.1, 10.10, 11.3)*
 - **T-INST-41a**: `loopx install --help` produces identical stdout, stderr, and exit code as `loopx install -h`. Run both in the same fixture. Assert: (a) stdout is byte-identical between the two invocations, (b) stderr is byte-identical, and (c) both exit 0. This proves the `--help` long form is a true alias for `-h`, consistent with the top-level and run help `--help` parity tests (T-CLI-03, T-CLI-41). *(Spec 4.2, 11.3)*
 - **T-INST-42**: `loopx install -h --unknown` → install help, exit 0 (unknown flag ignored under `-h`). *(Spec 4.2)*
 - **T-INST-42a**: `loopx install -h http://localhost:PORT/pkg.tar.gz` → install help, exit 0. Start a local HTTP server that tracks incoming requests. Assert: (a) help is shown, (b) the HTTP server received zero requests, and (c) `.loopx/` was not created or modified. Proves that `-h` makes no network requests even when a valid source is provided. *(Spec 4.2, 11.3)*
@@ -1368,6 +2735,12 @@ All install tests use local servers (HTTP, file:// git repos). No network access
 - **T-INST-43a**: `loopx install --workflow a --workflow b <source>` → usage error, exit code 1 (duplicate `--workflow`). *(Spec 4.2)*
 - **T-INST-43b**: `loopx install -w a --workflow b <source>` → usage error, exit code 1 (duplicate workflow flag — mixed short and long forms still count as a duplicate). *(Spec 4.2)*
 - **T-INST-44**: `loopx install -y -y <source>` → usage error, exit code 1 (duplicate `-y`). *(Spec 4.2)*
+- **T-INST-44a**: `loopx install --no-install --no-install <source>` → usage error, exit code 1 (duplicate `--no-install`). Per Spec 4.2, repeating `--no-install` is a usage error unless `-h` / `--help` is present. This extends the duplicate-flag rejection pattern established by T-INST-43 (`-w`), T-INST-43a (`--workflow`), T-INST-43b (mixed), and T-INST-44 (`-y`) to the new `--no-install` flag added by Spec 10.10. *(Spec 4.2, 10.10)*
+- **T-INST-44b**: `loopx install -h --no-install <source>` → install help, exit 0. The `-h` short-circuit ignores `--no-install` entirely (no validation of its presence or absence). Source is present, but help short-circuit suppresses install. Assert: (a) help stdout, (b) exit 0, (c) no source download / network activity, (d) `.loopx/` untouched. Extends T-INST-42 / T-INST-42a pattern to `--no-install`. *(Spec 4.2, 10.10, 11.3)*
+- **T-INST-44c**: `loopx install --help --no-install --no-install <source>` → install help, exit 0. The `--help` short-circuit also suppresses duplicate-`--no-install` usage errors — Spec 4.2 says the short-circuit ignores all other install-level arguments unconditionally (including duplicate or extraneous `--no-install`). Assert help output, exit 0, no duplicate-flag error on stderr. *(Spec 4.2, 10.10, 11.3)*
+- **T-INST-44d**: `loopx install --no-install -h <source>` → install help, exit 0. `--no-install` appearing before `-h` does not block the late-help short-circuit pattern (T-INST-49a–49g). Assert help output, exit 0. *(Spec 4.2, 10.10, 11.3)*
+- **T-INST-44e**: `loopx install --no-install --no-install -h <source>` → install help, exit 0. The late-help short-circuit fires unconditionally even when the preceding tokens include a duplicate `--no-install` (which would be a usage error per T-INST-44a if `-h` / `--help` were absent). Per SPEC 4.2, the `-h` / `--help` short-circuit ignores all other install-level arguments unconditionally — including duplicate `--no-install`. T-INST-44a covers the duplicate-flag rejection without help, T-INST-44c covers the `--help`-first-with-trailing-duplicate form, and T-INST-44d covers a single `--no-install` before late `-h`; this test pins down the specific combination of **duplicate `--no-install`** appearing **before** late `-h`. **Parameterize over both forms**: variant (a) `loopx install --no-install --no-install -h <source>`, variant (b) `loopx install --no-install --no-install --help <source>`. For each variant, assert: (a) install help on stdout (matches T-INST-41a's install-help reference), (b) exit code 0, (c) no duplicate-flag error on stderr (the short-circuit must suppress the would-be usage error from T-INST-44a), (d) no source download / network activity (verify via `withFakeGit` log being empty of clone invocations or by relying on the pre-network exit-0 surface), and (e) `.loopx/` (if pre-existing) is untouched. A buggy implementation that validated `--no-install` duplicates before applying the help short-circuit would surface the usage error and fail (b)/(c). *(Spec 4.2, 10.10, 11.3)*
+- **T-INST-44f**: `--no-install` has **no short form** — common single-character alias candidates are unrecognized install-scoped short flags. SPEC 4.2's `--no-install` row explicitly says "No short form." T-INST-45a (generic `-x` rejection) proves the parser rejects an arbitrary unknown short flag, but does not pin down the specific candidate aliases (`-n`, `-N`, `-i`, `-I`) that an implementer would most plausibly add as a hidden alias for `--no-install` based on the long-form's name. A buggy implementation that introduced a hidden `-n` or `-i` alias for `--no-install` (or that special-cased one of these short forms to *suppress* auto-install while still being parsed as a known install-scoped flag) would pass T-INST-45a — because that test exercises only `-x` — yet violate the SPEC 4.2 "No short form" clause. **Parameterize over the four most-plausible candidates**: variant (a) `loopx install -n <source>`, variant (b) `loopx install -N <source>`, variant (c) `loopx install -i <source>`, variant (d) `loopx install -I <source>`. For each variant, use a valid source (e.g., `org/repo` shorthand routed through `withFakeGit` to a local bare repo with one workflow containing `index.sh` + `package.json`, mirroring the T-INST-44a-class fixture shape). Wrap with `withFakeNpm({ logFile })` so any unintended auto-install would be observable. Assert: (a) **exit code 1** — the short flag is unrecognized at the install scope per SPEC 4.2 "Unrecognized flags within `install` ... are usage errors", (b) stderr references the unrecognized-flag rejection (matching T-INST-45 / T-INST-45a's usage-error surface; the exact wording is not pinned), (c) **the fake-npm shim log records zero invocations** — the install never reaches the auto-install pass; this catches a buggy implementation that silently aliased one of these short flags to `--no-install` and proceeded with the file-level install (which would surface as exit 0 plus a successful commit with no `npm install`), and (d) **`.loopx/` (if pre-existing) is untouched and no new workflow directory is committed** — the usage error fires at parser time, before any source acquisition or commit, identical to T-INST-45 / T-INST-45a's pre-network exit surface; verify via `withFakeGit`'s log being empty of clone invocations. Together with the strengthened T-INST-41 assertion (f) (no short alias advertised in install help text), this closes the SPEC 4.2 "No short form" clause across both surfaces — help text and parser. *(Spec 4.2, 10.10)*
 - **T-INST-45**: `loopx install --unknown <source>` → usage error, exit code 1 (unrecognized flag). *(Spec 4.2)*
 - **T-INST-45a**: `loopx install -x <source>` → usage error, exit code 1 (unrecognized short flag). This is the install-scoped counterpart to T-CLI-72 (`loopx run -x ralph`), ensuring short flags are rejected identically to long flags. *(Spec 4.2)*
 - **T-INST-46**: `loopx install -h -w a -w b` shows install help and exits 0 (duplicate `-w` not rejected under help). *(Spec 4.2)*
@@ -1385,9 +2758,18 @@ All install tests use local servers (HTTP, file:// git repos). No network access
 - **T-INST-49f**: `loopx install -w -h` shows install help and exits 0. A naive parser would consume `-h` as the operand for `-w`, but the `-h` short-circuit fires unconditionally when `-h` is present — all other install-level arguments are ignored. This is the missing-operand counterpart to T-INST-49a–49d (which cover invalid or duplicate flags before `-h`). *(Spec 4.2)*
 - **T-INST-49g**: `loopx install --workflow --help` shows install help and exits 0. Long-form counterpart to T-INST-49f: `--workflow` would consume `--help` as its operand in naive parsing, but the help short-circuit ignores all other arguments unconditionally. *(Spec 4.2)*
 
+#### Install-scoped `--` Rejection
+
+SPEC 4.2 enumerates only `-w` / `--workflow`, `-y`, `--no-install`, and `-h` / `--help` as recognized install-scoped flags. `--` is not a recognized install-scoped token (no end-of-options separator semantics, no positional separator). T-CLI-RUN-DASHDASH-01 through 07 cover the run-scoped surface, T-CLI-TOP-DASHDASH-01 covers the top-level surface, and T-INST-45 covers `--unknown` rejection generally; this block pins down the install-scoped `--` rejection specifically and its interaction with the `-h` / `--help` short-circuit (which Spec 4.2 says ignores all other install-level arguments unconditionally).
+
+- **T-INST-DASHDASH-01**: `loopx install -- <source>` → usage error, exit code 1. The `<source>` argument follows the `--` token and would be the install source if `--` were silently treated as an end-of-options separator, but `--` is not a recognized install-scoped token per SPEC 4.2. **The `<source>` must be a genuinely valid supported source** (per SPEC 10.1: `org/repo` shorthand, a `file://…repo.git` URL pointing to a local bare repo, or a localhost tarball URL) that would succeed as a normal `loopx install <source>` invocation — otherwise the test has a false-pass hazard: a buggy implementation that silently consumed `--` could still fail later with an "unsupported source" error on an unsupported local-path source and accidentally exit 1 for the wrong reason, making exit-code-1 a non-distinguishing signal. Run `loopx install -- <valid-source>` where `<valid-source>` is, e.g., a `file:///tmp/bare-repos/my-workflow.git` URL served by `startLocalGitServer` (section 2.3), or a localhost `.tar.gz` URL served by `startLocalHTTPServer`. To remove any residual ambiguity about whether the `--` rejection fired or a later source-resolution step did, pre-verify the same `<valid-source>` succeeds in a separate `loopx install <valid-source>` invocation (without the `--` token) against a fresh project to confirm the source is genuinely installable; then in the test proper, assert: (a) exit code 1 (usage error per SPEC 12 / SPEC 4.2 unrecognized-flag rule), (b) stderr surfaces a usage-error / unrecognized-token category mentioning `--` — the exact wording is implementation-defined but must distinguish a usage-error-category message from a "source unsupported" message (i.e., the failure must be about the `--` token, not about the source), (c) no source download / clone / network activity occurred (verify by asserting the `withFakeGit` or `startLocalGitServer` / `startLocalHTTPServer` log records zero hits for the test URL during this invocation), (d) no `.loopx/<workflow>` was committed, and (e) `.loopx/` (if pre-existing) is untouched. A buggy implementation that silently consumed `--` as an end-of-options marker and then proceeded with `<valid-source>` as the install source would produce exit 0 and surface a successful install — an observable distinct failure mode. *(Spec 4.2, 10, 10.1, 12)*
+- **T-INST-DASHDASH-02**: `loopx install <source> --` → usage error, exit code 1. Trailing `--` after the source is rejected just like leading `--`. Run `loopx install <valid-source> --` where `<valid-source>` is the same genuinely valid source used by T-INST-DASHDASH-01 (e.g., `file:///tmp/bare-repos/my-workflow.git` or a localhost `.tar.gz` URL), pre-verified to succeed without the trailing `--`. Assert: (a) exit code 1, (b) stderr surfaces a usage-error / unrecognized-token category mentioning `--` (not "source unsupported"), (c) no source download / clone / network activity occurred (verify via the same fake-server / shim log as in T-INST-DASHDASH-01), (d) no `.loopx/<workflow>` was committed, and (e) `.loopx/` is untouched. Trailing-`--` counterpart to T-INST-DASHDASH-01 (leading), proving `--` is rejected at any position when the help short-circuit is not present. Using a valid source for both positional forms ensures the test cannot false-pass by an unrelated "unsupported source" rejection downstream of a buggy `--` acceptance. *(Spec 4.2, 10, 10.1, 12)*
+- **T-INST-DASHDASH-03**: `loopx install -h -- <source>` → install help, exit 0. The `-h` short-circuit fires before any `--` rejection, suppressing the would-be usage error from T-INST-DASHDASH-01. Per SPEC 4.2 install short-circuit clause: "When `-h` / `--help` is present, loopx shows install help, exits 0, and ignores all other install-level arguments unconditionally" — this includes `--` and any subsequent tokens. Assert: (a) exit code 0, (b) stdout is install help (matches T-INST-41a's install-help reference), (c) no source download / network activity occurred, (d) `.loopx/` is untouched, and (e) stderr contains no usage-error message about `--`. Help-short-circuit counterpart for `--`, mirroring the patterns in T-INST-42 (`-h --unknown`), T-INST-44b (`-h --no-install <source>`), and T-CLI-RUN-DASHDASH-04 (`run -h -- ralph`). *(Spec 4.2, 10, 11.3)*
+- **T-INST-DASHDASH-04**: `loopx install --help -- <source>` → install help, exit 0. Long-form counterpart to T-INST-DASHDASH-03, completing help-short-circuit-suppresses-`--` coverage for both `-h` and `--help`. Assert: (a) exit code 0, (b) stdout is install help, (c) no source download / network activity, (d) `.loopx/` is untouched, (e) stderr contains no usage-error message about `--`. Mirrors the long-form-help-short-circuit pattern from T-INST-42e / T-INST-49d. *(Spec 4.2, 10, 11.3)*
+
 #### Workflow Classification — Single-Workflow Source
 
-- **T-INST-50**: Git repo with root-level `index.ts`, a non-script file (`package.json`), and a pure non-script root directory (`docs/` containing only `.md` files — no supported script extensions) → single-workflow source. Entire repo installed as `.loopx/<repo-name>/`. Assert the workflow directory contains all root-level files including non-script files (`package.json`) **and** non-script directories (`docs/`). This covers the ADR-0003 rule that all root files and directories are copied for single-workflow sources, including directories that contain no script-extension files. *(Spec 10.3)*
+- **T-INST-50**: Git repo with root-level `index.ts`, a non-script file (`package.json`), and a pure non-script root directory (`docs/` containing only `.md` files — no supported script extensions) → single-workflow source. Entire repo installed as `.loopx/<repo-name>/`. Assert the workflow directory contains all root-level files including non-script files (`package.json`) **and** non-script directories (`docs/`). This covers the ADR-0003 rule that all root files and directories are copied for single-workflow sources, including directories that contain no script-extension files. **Pass `--no-install` per the section 4.10 auto-install-awareness rule** — the workflow's top-level `package.json` would otherwise trigger auto-install, and this test's contract is classification/copy, not auto-install. *(Spec 10.3)*
 - **T-INST-50a**: Git repo with root-level `index.js` → single-workflow source. Installed as `.loopx/<repo-name>/`. This extends install-path extension coverage (T-INST-50 covers `.ts`) to positively verify that `.js` is recognized as a supported script extension in the install single-workflow classification codepath. *(Spec 10.3, 2.1)*
 - **T-INST-50b**: Parameterized: single-workflow root classification for all five supported extensions. For each extension in [`.sh`, `.js`, `.jsx`, `.ts`, `.tsx`], create a git repo with a single root-level `index.<ext>` file. Run `loopx install <source>`. Assert: the source is classified as single-workflow and installed as `.loopx/<repo-name>/`. T-INST-50 covers `.ts` and T-INST-50a covers `.js` individually; this parameterized test closes the gaps for `.sh`, `.jsx`, and `.tsx` and exercises all five extensions uniformly in the single-workflow root classification codepath. *(Spec 10.3, 2.1)*
 - **T-INST-51**: Git repo with root-level `index.ts` and a `lib/` subdirectory containing `.ts` files → still single-workflow (root-level script files take precedence unconditionally). `lib/` is workflow content, not a separate workflow. Assert `.loopx/<repo-name>/lib/` exists. *(Spec 10.3)*
@@ -1403,7 +2785,7 @@ All install tests use local servers (HTTP, file:// git repos). No network access
 - **T-INST-53b**: Multi-workflow git repo where one subdirectory qualifies via `index.tsx`. Source contains `ralph/index.sh` and `other/index.tsx`, with no root-level script files → both installed as `.loopx/ralph/` and `.loopx/other/`. This extends install-path extension coverage to positively verify that `.tsx` is recognized in the install multi-workflow classification codepath. *(Spec 10.3, 2.1)*
 - **T-INST-53c**: Parameterized: multi-workflow subdirectory classification for all five supported extensions. For each extension in [`.sh`, `.js`, `.jsx`, `.ts`, `.tsx`], create a multi-workflow git repo where one subdirectory (`target/`) qualifies via a single `index.<ext>` file, alongside another valid workflow `other/index.sh`, with no root-level script files. Run `loopx install <source>`. Assert: both `target` and `other` are installed. T-INST-53 covers `.sh`, T-INST-53a covers `.jsx`, and T-INST-53b covers `.tsx` individually; this parameterized test closes the gaps for `.js` and `.ts` and exercises all five extensions uniformly in the multi-workflow subdirectory classification codepath. *(Spec 10.3, 2.1)*
 - **T-INST-54**: Multi-workflow repo: repo-root support files (README, LICENSE, `package.json`, etc.) are NOT copied into `.loopx/`. Only workflow directories are installed. Assert that a root `package.json` in the source does not create `.loopx/package.json` **and** that a root `README.md` in the source does not create `.loopx/README.md`. Both file types are repo-level support files that must be excluded when only workflow directories are copied. *(Spec 10.3)*
-- **T-INST-54a**: Multi-workflow install preserves workflow-internal non-script files and subdirectories. Source repo contains `ralph/index.ts`, `ralph/package.json`, `ralph/lib/helpers.ts`, and `ralph/README.md` (plus `other/index.sh` to force multi-workflow classification). After install, assert `.loopx/ralph/package.json`, `.loopx/ralph/lib/helpers.ts`, and `.loopx/ralph/README.md` are all present. This verifies that the entire workflow directory — not just discovered script files — is copied. *(Spec 10.3)*
+- **T-INST-54a**: Multi-workflow install preserves workflow-internal non-script files and subdirectories. Source repo contains `ralph/index.ts`, `ralph/package.json`, `ralph/lib/helpers.ts`, and `ralph/README.md` (plus `other/index.sh` to force multi-workflow classification). After install, assert `.loopx/ralph/package.json`, `.loopx/ralph/lib/helpers.ts`, and `.loopx/ralph/README.md` are all present. This verifies that the entire workflow directory — not just discovered script files — is copied. **Pass `--no-install` per the section 4.10 auto-install-awareness rule** — `ralph/package.json` would otherwise trigger the post-commit auto-install pass, and this test's contract is the file-copy preservation rule, not auto-install behavior. *(Spec 10.3)*
 - **T-INST-54b**: Multi-workflow source-root `package.json` is ignored during validation and version checking. Source repo contains `ralph/index.sh`, `other/index.sh`, and a repo-root `package.json` that is either invalid JSON (e.g., `{broken`) or declares a loopx version range not satisfied by the running version. `loopx install <source>` succeeds, installing both workflows. Assert: no warning or error on stderr related to `package.json` or version mismatch. In the workflow model, only each workflow's own `package.json` matters for version checking — the repo-root file is a support file that is neither copied (T-INST-54) nor read for validation. *(Spec 10.3, 10.6)*
 - **T-INST-54c**: Multi-workflow install does not copy root support directories. Source repo contains `ralph/index.sh`, `other/index.sh`, `docs/README.md`, and `shared/config.json`. After install, assert `.loopx/ralph/` and `.loopx/other/` exist, but `.loopx/docs/` and `.loopx/shared/` do not exist. This is the directory counterpart to T-INST-54 (which covers root support files) — T-INST-55 verifies that non-workflow subdirectories are silently skipped during classification, but does not assert their absence from the destination. A buggy installer that correctly classifies workflows but still copies all subdirectories into `.loopx/` would pass T-INST-55 but fail here. *(Spec 10.3)*
 - **T-INST-54d**: Multi-workflow tarball source-root `package.json` is ignored during validation and version checking. Create a `.tar.gz` whose source root (after any wrapper-directory stripping) contains workflow subdirectories `ralph/index.sh` and `other/index.sh`, plus a source-root `package.json` that is either invalid JSON (e.g., `{broken`) or declares a loopx version range not satisfied by the running version. `loopx install <tarball-url>` succeeds, installing both workflows. Assert: (a) exit code 0, (b) both `.loopx/ralph/` and `.loopx/other/` are installed, (c) no warning or error on stderr related to `package.json` or version mismatch, and (d) `.loopx/package.json` does not exist (the source-root file was not copied). This is the tarball counterpart to T-INST-54b (git multi-workflow): per SPEC 10.2, classification after extraction is source-type-agnostic, so the "source-root `package.json` is not read for multi-workflow classification or version checking" rule must hold for both source types. *(Spec 10.2, 10.3, 10.6)*
@@ -1421,7 +2803,84 @@ All install tests use local servers (HTTP, file:// git repos). No network access
 - **T-INST-56e**: Legacy directory-script source is rejected as zero-workflow without migration-guidance messaging. Create a source root with a `package.json` whose `main` points to a nested file (e.g., `{ "main": "src/app/run.js" }`) and no top-level files with supported script extensions (the script file lives only inside a nested subdirectory like `src/app/run.js`). Run `loopx install <source>`. Assert: (a) exit code 1, (b) the error indicates no installable workflows were found, and (c) — **structurally** rather than by prose blacklisting — stderr does not contain a migration-guidance or deprecation warning as a separate output category alongside the zero-workflow error. Concretely: the stderr output is limited to the standard "no installable workflows found" error (and any unrelated warnings that would be emitted regardless of the legacy layout). There is no additional warning/notice/advisory line whose subject is the legacy directory-script layout (the `main` field, the nested script file, or the `package.json`-without-top-level-scripts shape are not flagged in any extra output category beyond the routine zero-workflow rejection). Prose-level phrase matching is intentionally avoided — the check targets the presence of a distinct migration-warning output category, not specific wording. T-INST-56a proves the zero-workflow rejection for this shape; this test extends it with the structural anti-migration-messaging assertion, aligning install behavior with ADR-0003's explicit "no legacy compatibility or migration tooling" consequence and mirroring runtime coverage in T-DISC-10a (flat script) and T-DISC-20c (directory script). *(Spec 10.3)*
 - **T-INST-56c**: Source root containing only `index.mjs` at root level (no files with supported extensions) → zero-workflow error. `.mjs` is not a supported script extension (Spec 2.1), so no script files are found at the root level and no subdirectories qualify as workflows. This is the install-classification counterpart to T-DISC-06, which covers `.mjs` being unrecognized at runtime discovery. *(Spec 10.3, 2.1)*
 - **T-INST-56d**: Source root containing only `index.cjs` at root level → zero-workflow error. `.cjs` is not a supported script extension. This is the install-classification counterpart to T-DISC-07. *(Spec 10.3, 2.1)*
-- **T-INST-56b**: Tarball source with no installable workflows → error. Create a `.tar.gz` whose source root (after wrapper-directory stripping) contains no root-level script files and no subdirectories that qualify as workflows (e.g., only `README.md` and a `lib/` directory with `.ts` files nested inside). `loopx install <tarball-url>` → exits with code 1 with an error indicating no installable workflows were found. This is the tarball counterpart to T-INST-56 (git zero-workflow) — the classification logic is source-type-agnostic, so both source types must reject zero-workflow sources. *(Spec 10.3, 10.2)*
+- **T-INST-56f**: Source root containing only `index.SH` at root level (uppercase extension) → zero-workflow error. Per SPEC 2.1 the supported script extensions are `.sh`, `.js`, `.ts`, `.jsx`, `.tsx` (lowercase); uppercase variants (`.SH`, `.JS`, etc.) are not supported. The install-classification codepath must enforce the same extension rules as runtime discovery (T-DISC-15c covers runtime uppercase-unsupported). Prepare a source whose root contains only `index.SH` (uppercase) and no other files with supported extensions. `loopx install <source>` → exit code 1 with a zero-workflow error. Together with T-INST-56c / T-INST-56d (`.mjs` / `.cjs` unsupported), this pins down the install-classification extension-matching rule parity with runtime discovery. *(Spec 10.3, 2.1)*
+- **T-INST-56g**: Multi-workflow candidate subdirectory containing only `index.TS` (uppercase) is skipped as non-workflow. Per SPEC 2.1 extension rules (lowercase-only), a subdirectory whose only top-level file is an uppercase-extension script does not qualify as a workflow. Prepare a multi-workflow source where `ralph/` contains `index.sh` (valid) and `other/` contains only `index.TS` (uppercase, unsupported). Run `loopx install <source>`. Assert: (a) exit code 0, (b) `.loopx/ralph/` is installed with `index.sh`, (c) `.loopx/other/` does **not** exist (the subdirectory was skipped because `index.TS` does not match the supported-extension pattern — it was not classified as a workflow). A buggy implementation that case-insensitively matched extensions would install `other/` as a workflow and fail this test. *(Spec 10.3, 2.1)*
+- **T-INST-56h**: Single-workflow source with a valid root-level `index.sh` plus an additional uppercase-extension file (`helper.TS`) at the root level: the uppercase file is copied as **non-script content**, not treated as a script. SPEC 10.3 says install preserves the source's non-script content alongside recognized script files; a file whose extension is not in the supported set is non-script content. Prepare a source whose root contains `index.sh` (valid single-workflow trigger) and `helper.TS` (uppercase — not a supported script extension). Run `loopx install <source>`. Assert: (a) exit code 0, (b) `.loopx/<name>/` contains `index.sh` (classified and copied as a script), (c) `.loopx/<name>/helper.TS` exists byte-for-byte (copied as non-script content — not validated, not renamed, not discovered as a script), and (d) `loopx run -h` does not list `helper` as a script of the installed workflow (validating that the runtime-discovery extension rules also reject `helper.TS` at runtime, confirming round-trip parity). Together with T-INST-56f / T-INST-56g, this completes the uppercase-extension install-classification coverage: rejected at the root-only and subdirectory-only layers (T-INST-56f / T-INST-56g) and preserved-as-non-script-content in valid-workflow sources (this test). *(Spec 10.3, 2.1, 5.1)*
+- **T-INST-56b**: Tarball source with no installable workflows → error. Create a `.tar.gz` whose source root (after wrapper-directory stripping) contains no root-level script files and no subdirectories that qualify as workflows. For example, the tarball root contains `README.md` (non-script content) and `lib/nested/helper.ts` (a `.ts` file placed **inside a nested subdirectory below** `lib/`, not at `lib/*.ts` top-level). `lib/` therefore does **not** qualify as a workflow because workflow detection per SPEC 10.3 / 5.1 requires at least one top-level supported-extension script file directly inside the subdirectory; a `.ts` file nested one level deeper does not satisfy that rule. Explicitly: there must be no files matching `lib/*.{sh,js,ts,jsx,tsx}` at the top level of `lib/`. `loopx install <tarball-url>` → exits with code 1 with an error indicating no installable workflows were found. This is the tarball counterpart to T-INST-56 (git zero-workflow) — the classification logic is source-type-agnostic, so both source types must reject zero-workflow sources. *(Spec 10.3, 10.2)*
+- **T-INST-56i**: Source root containing only a directory whose name has a supported script extension → zero-workflow error. SPEC 10.3 / 5.1 require single-workflow classification's "root-level script files" trigger to match top-level **files** with supported extensions; a top-level directory whose name happens to end in `.sh`/`.ts`/`.js`/`.jsx`/`.tsx` is not a file and does not satisfy the trigger. Prepare a git source whose root contains a single top-level directory named `index.sh/` (created with `mkdir -p index.sh`, with optional unrelated content nested inside, e.g., `index.sh/notes.md`) and **no** top-level files with supported extensions and **no** subdirectories that qualify as workflows. Run `loopx install <source>` → exit code 1 with a zero-workflow error. Assert: (a) the source is **not** classified as single-workflow (the directory `index.sh/` did not satisfy the root-level-script-file trigger), and (b) the error is the "no installable workflows found" error, not a classification-then-validation error (e.g., not "invalid script name `index.sh`" — `index.sh/` was never treated as a script in the first place because it is a directory). This is the file-vs-directory counterpart to T-INST-56f / T-INST-56g (which test uppercase-extension files); together they pin down that install classification matches both on extension case-sensitivity and on entry type (file, not directory). A buggy implementation that enumerated root-level entries by name pattern (matching `*.{sh,ts,js,jsx,tsx}`) without checking whether the entry resolves to a regular file would wrongly classify the source as single-workflow and either fail to copy `index.sh` (it is a directory, not a file) or copy it as a directory and then fail script-name validation at install-time. *(Spec 10.3, 10.4, 5.1, 2.1)*
+
+#### Install Source Symlinks
+
+SPEC 10.11 pins down install-time symlink semantics: install-time discovery follows symlinks under the same entry-type policy as runtime (SPEC 5.1) — a symlinked workflow directory can qualify as a workflow and a symlinked script file can qualify as a script, with names derived from the symlink entry's own name. During staging / copy, symlinks are **materialized** rather than preserved: the destination contains a real directory or file copied from the symlink target, never a symlink pointing back into the temporary clone / extraction directory. Symlinks that are part of a selected workflow must resolve to existing paths within the install source root; broken symlinks, cycles, and out-of-source targets are preflight-atomic rejection failures. Under `-w`, only the selected workflow's symlinks are validated and materialized.
+
+Per SPEC 10.2 the post-acquisition classification path is source-type-agnostic, so each test below is parameterized over **both** source types — git source (local bare repo, no network) and tarball source (local HTTP server, no network) — to prove the symlink behavior is enforced on both code paths.
+
+- **T-INST-55f**: Install source containing a symlinked workflow subdirectory is materialized as a real directory. Multi-workflow source root containing a top-level real directory `internal/real-workflow/` (with `index.sh`) and a top-level symlink `alias -> internal/real-workflow` (i.e., a multi-workflow source where `alias/` is a symlinked workflow entry). Run `loopx install --no-install <source>` (no `-w`, so all qualifying workflows are installed). Assert: (a) exit code 0, (b) `.loopx/alias/` exists and is a **real directory** (`fs.lstat(...).isSymbolicLink()` is `false`), (c) `.loopx/alias/index.sh` exists and is a **real file** with the same byte-for-byte content as the symlink target's `index.sh`, (d) the workflow runs successfully via `loopx run -n 1 alias` (proving the materialized copy is executable, not just present), (e) `.loopx/internal/` does not exist as a workflow at the destination (a non-workflow source-root subdirectory containing a workflow subdirectory does not count as a top-level workflow per SPEC 10.3 — top-level workflow detection is non-recursive), and (f) the workflow name is `alias` (the symlink entry's own name), not `real-workflow` (the target's basename). **Parameterized across git and tarball sources** per SPEC 10.2 / 10.11. **`--no-install` per the section 4.10 auto-install-awareness rule** — the test's contract is materialization, not auto-install behavior. *(Spec 10.11, 10.3, 5.1, 10.2)*
+- **T-INST-55g**: Install source containing a symlinked entry script inside a workflow is materialized as a real file, with the script name derived from the symlink entry's own name (not the target's basename). Source workflow `ralph/` containing a real helper file `ralph/lib/original-entry.sh` (with a marker `echo` and `exit 0`) and a top-level symlink `ralph/index.sh -> lib/original-entry.sh` (i.e., `index.sh` is a symlinked script entry within the workflow whose target has a **distinct basename** — `original-entry` ≠ `index` — so the test discriminates between symlink-name and target-basename derivation). The target `lib/original-entry.sh` is a nested file (inside the non-top-level `lib/` subdirectory), so it is not itself a top-level script per SPEC 2.1's non-recursive script-discovery rule. Run `loopx install --no-install <source>`. Assert: (a) exit code 0, (b) `.loopx/ralph/index.sh` exists and is a **real file** (`fs.lstat(...).isSymbolicLink()` is `false`), (c) the file content matches the symlink target's content byte-for-byte (`lib/original-entry.sh`'s contents), (d) `loopx run -n 1 ralph` runs the materialized script and the marker side effect is observed (proving the copy is functional, not just byte-equivalent — and that the script is reachable as the workflow's default `index` entry, not via the target basename), and (e) `original-entry` is **not** a top-level discovered script name in `.loopx/ralph/` — `loopx run -n 1 "ralph:original-entry"` fails with a missing-script error. A buggy implementation that derived the script name from the symlink target's basename (`original-entry`) rather than from the symlink entry's own name (`index`) would either create a script named `original-entry` (failing assertion (d) because there would be no `index` to run as default) or expose `original-entry` as a discoverable script (failing assertion (e)). **Parameterized across git and tarball sources** per SPEC 10.2 / 10.11. **`--no-install` per the section 4.10 auto-install-awareness rule** — the source workflow's directory does not contain a top-level `package.json` in this fixture so auto-install would not fire anyway, but `--no-install` is included for consistency with the rest of the symlink suite. *(Spec 10.11, 10.3, 5.1, 10.2)*
+- **T-INST-55h**: Broken or out-of-source symlink in a selected workflow is rejected preflight-atomically. Three sub-cases, each tested independently. The three sub-cases must keep the SPEC 10.11 failure classes **distinct** — a "broken" case must have an unresolvable target, a "cycle" case must form a self-referential symlink chain, and an "out-of-source" case must point to a target that **actually exists on disk** but resolves outside the install source root (otherwise the out-of-source branch collapses into the broken-symlink branch and the test fails to discriminate the two rejection paths):
+    - **(h-broken)**: Source workflow `ralph/` contains `ralph/index.sh -> nonexistent-target` (a symlink whose target does not exist anywhere on disk).
+    - **(h-cycle)**: Source workflow `ralph/` contains `ralph/index.sh -> a` and `ralph/a -> b` and `ralph/b -> a` (a cycle in the symlink chain — the script entry resolves through a cycle that never terminates at a real file).
+    - **(h-out-of-source)**: Before constructing the install source, the test creates a real, controlled file at an absolute path **outside** the install source root (e.g., `<test-isolated-tmp>/outside-of-source/real-target.sh` containing valid script content — a `bash` script with `exit 0`); the install source's `ralph/index.sh` is a symlink whose **target is the absolute path** of that out-of-source file (or a reliably resolving relative path that traverses **above** the install source root and lands on the controlled file). The test must verify before invoking `loopx install` that the symlink resolves to an existing file via `fs.realpath` from the install source root — this discriminates this sub-case from `(h-broken)`. The target is created in a test-isolated temp directory (not in `/etc/`, `/usr/`, or any system path) so the test does not depend on system files such as `/etc/passwd`, which may not exist in minimal containers and pollutes the failure semantics across sub-cases.
+
+  For each sub-case, run `loopx install --no-install <source>`. Assert: (a) exit code 1, (b) the install fails preflight-atomically — `.loopx/` either does not exist or contains no `.loopx/ralph/` entry (no partial install was committed), and (c) stderr contains an error message identifying the failing symlink (the test does not pin the exact wording, only that `ralph` and `index.sh` are mentioned in the error context). For sub-case `(h-out-of-source)` specifically, the test must additionally verify that the controlled out-of-source target file still exists after the install fails — proving the rejection happened before any copy step touched it (and giving an extra signal that the test's preflight-traversal verification ran on a real existing file, not a broken target). **Do not assert on the implementation-private staging directory** — its path/name is not black-box observable without a seam (see known gap T-INST-79a — section 4.10 "Staging-directory Cleanup Visibility"); this test is limited to the externally visible "no destination workflow committed" surface. **Parameterized across git and tarball sources** per SPEC 10.2 / 10.11. **`--no-install` per the section 4.10 auto-install-awareness rule** — the install fails before commit so auto-install would not fire anyway, but `--no-install` is included for consistency. *(Spec 10.11, 10.7, 10.9)*
+- **T-INST-55i**: Under `-w`, a bad symlink in an unselected sibling workflow does not block install of the selected workflow, but the same bad symlink in the selected workflow is fatal. Per SPEC 10.11, "only symlinks that are part of the selected workflow are validated and materialized" — so the unselected-sibling-invisibility rule must apply uniformly to **all three** SPEC 10.11 failure classes (broken, cycle, out-of-source), not just broken symlinks. The test parameterizes the bad-symlink class across all three failure classes, mirroring the T-INST-55h structure for the selected-workflow case. Multi-workflow source containing two workflows: `ralph/index.sh` (a real, valid script file) and a sibling `broken/` workflow whose `index.sh` is bad in one of three ways (each sub-case below uses a distinct fixture). The same fixture-distinctness requirement as T-INST-55h applies — out-of-source uses a real, controlled file outside the install source root via absolute path:
+    - **(i-broken)**: `broken/index.sh -> nonexistent-target` (broken).
+    - **(i-cycle)**: `broken/index.sh -> a`, `broken/a -> b`, `broken/b -> a` (cycle).
+    - **(i-out-of-source)**: Before constructing the install source, the test creates a real, controlled file at `<test-isolated-tmp>/outside-of-source/real-target.sh`. The install source's `broken/index.sh` is a symlink whose target is the absolute path of that out-of-source file (or a reliably resolving relative path landing on it). The test must verify before invoking `loopx install` that the symlink resolves to an existing file via `fs.realpath` from the install source root — distinguishing this sub-case from `(i-broken)`.
+
+  For each sub-case, perform two invocations:
+    - **(unselected-bad)**: Run `loopx install --no-install -w ralph <source>` (selecting only the valid workflow). Assert: (a) exit code 0, (b) `.loopx/ralph/` is installed and contains `index.sh` as a real file, (c) `.loopx/broken/` does not exist (selective install only writes the selected workflow), and (d) stderr contains no error or warning about the bad symlink in `broken/` — per SPEC 10.11 "Symlinks in unselected workflow directories ... are ignored" combined with the SPEC 10.8 selective-validation rule, the bad symlink in the unselected sibling is not validated regardless of which SPEC 10.11 failure class it represents. For `(i-out-of-source)` specifically, additionally assert that the controlled out-of-source target file still exists after install completes — proving no copy step crossed the source-root boundary even though the unselected sibling's symlink pointed there.
+    - **(selected-bad)**: Run `loopx install --no-install -w broken <source>` (selecting the workflow with the bad symlink). Assert: (a) exit code 1, (b) the install fails preflight-atomically — neither `.loopx/broken/` nor `.loopx/ralph/` is committed, and (c) stderr contains an error identifying the bad symlink in `broken/`. **Do not assert on the implementation-private staging directory** for the same reason as T-INST-55h (see known gap T-INST-79a — section 4.10 "Staging-directory Cleanup Visibility").
+
+  Together the three sub-cases × two invocations prove the SPEC 10.11 + SPEC 10.8 interaction across the full SPEC 10.11 failure-class set: any unselected-sibling bad symlink is invisible under `-w` (regardless of class), but the same defect in the selected workflow is always fatal — `-w` does not relax symlink validation for the selected workflow, and the unselected-invisibility rule does not depend on which class of bad symlink the sibling has. A buggy implementation that special-cased the broken-symlink class but eagerly walked cycles or resolved out-of-source targets on unselected siblings (e.g., infinite-looping on the cycle, or copying out-of-source content) would fail this test. **Parameterized across git and tarball sources** per SPEC 10.2 / 10.11. **`--no-install` per the section 4.10 auto-install-awareness rule.** *(Spec 10.11, 10.8, 10.7)*
+- **T-INST-55j**: Symlinked **non-script file** inside a selected workflow is materialized as a real file. SPEC 10.11 normatively says "Symlinked non-script files or directories inside a selected workflow's copied content are likewise materialized as real files or directories." T-INST-55g covers a symlinked **script** entry; this test extends that materialization rule to **non-script** content inside a selected workflow, which is a separate code path (workflow-content copy walks all files, not just discovered scripts). Source workflow `ralph/` containing a real script entry `ralph/index.sh` (so the workflow definitely qualifies), a real helper file `ralph/docs/source.md` (with deterministic content `"non-script content"`), and a top-level non-script symlink `ralph/README.md -> docs/source.md`. Run `loopx install --no-install <source>`. Assert: (a) exit code 0, (b) `.loopx/ralph/README.md` exists and is a **real file** (`fs.lstat(...).isSymbolicLink()` is `false`), (c) the file content matches `docs/source.md` byte-for-byte (`"non-script content"`), and (d) `.loopx/ralph/docs/source.md` also exists as a real file with the same content (the symlink target inside the workflow is preserved alongside the materialized symlink — both copies exist on disk). A buggy implementation that only materialized symlinks for files matching script-extension patterns would either preserve `README.md` as a symlink (failing assertion (b)) or skip it entirely (failing assertion (c)). **Parameterized across git and tarball sources** per SPEC 10.2 / 10.11. **`--no-install` per the section 4.10 auto-install-awareness rule.** *(Spec 10.11, 10.3, 10.2)*
+- **T-INST-55k**: Symlinked **non-script directory** inside a selected workflow is materialized as a real directory. SPEC 10.11 normatively says "Symlinked non-script files or directories inside a selected workflow's copied content are likewise materialized as real files or directories." T-INST-55f covers a symlinked top-level **workflow** directory; this test extends the materialization rule to **non-script directories nested inside** a selected workflow's copied content (a separate code path — top-level workflow detection follows symlinks for classification, but this test exercises symlinked subdirectories that are part of workflow content rather than the workflow root itself). Source workflow `ralph/` containing a real script entry `ralph/index.sh` (so the workflow qualifies), a real shared-assets directory `ralph/shared-assets/` containing files `ralph/shared-assets/asset1.txt` (content `"asset-one"`) and `ralph/shared-assets/asset2.txt` (content `"asset-two"`), and a top-level symlinked directory `ralph/assets -> shared-assets`. Run `loopx install --no-install <source>`. Assert: (a) exit code 0, (b) `.loopx/ralph/assets` exists and is a **real directory** (`fs.lstat(...).isSymbolicLink()` is `false`), (c) `.loopx/ralph/assets/asset1.txt` and `.loopx/ralph/assets/asset2.txt` are both real files with content `"asset-one"` and `"asset-two"` respectively, and (d) `.loopx/ralph/shared-assets/` also exists as a real directory with the same files (both the symlinked spelling `assets/` and the original target `shared-assets/` are present in the destination). A buggy implementation that only materialized file symlinks (and preserved directory symlinks) would fail assertion (b). **Parameterized across git and tarball sources** per SPEC 10.2 / 10.11. **`--no-install` per the section 4.10 auto-install-awareness rule.** *(Spec 10.11, 10.3, 10.2)*
+- **T-INST-55l**: Broken / cyclic / out-of-source **non-script** symlinks inside a selected workflow are rejected preflight-atomically. SPEC 10.11's rejection rule applies to "symlinks that are part of a selected workflow" without restricting to script entries — non-script symlinked content inside a selected workflow must satisfy the same target-resolution rule. T-INST-55h covers the rejection rule for symlinked **script** entries; this test extends the rejection rule to **non-script** symlinked content. The same fixture-distinctness requirement as T-INST-55h applies — the three sub-cases must keep the SPEC 10.11 failure classes distinct (broken vs. cycle vs. existing-but-out-of-source). Three sub-cases, each tested independently, each retaining a real `ralph/index.sh` so the workflow definitely qualifies and the test isolates the non-script-symlink rejection branch:
+    - **(l-broken)**: Source workflow `ralph/` contains real `ralph/index.sh` plus a non-script symlink `ralph/README.md -> nonexistent-target` (target does not exist anywhere on disk).
+    - **(l-cycle)**: Source workflow `ralph/` contains real `ralph/index.sh` plus three non-script symlinks `ralph/README.md -> a`, `ralph/a -> b`, `ralph/b -> a` (a cycle in the symlink chain — `README.md` resolves through a cycle that never terminates at a real file).
+    - **(l-out-of-source)**: Before constructing the install source, the test creates a real, controlled file at an absolute path **outside** the install source root (e.g., `<test-isolated-tmp>/outside-of-source/real-readme.md` containing deterministic content — a plain `"out-of-source non-script content"` text file); the install source's `ralph/README.md` is a non-script symlink whose **target is the absolute path** of that out-of-source file (or a reliably resolving relative path that traverses **above** the install source root and lands on the controlled file). The test must verify before invoking `loopx install` that the symlink resolves to an existing file via `fs.realpath` from the install source root — this discriminates this sub-case from `(l-broken)`. The target is created in a test-isolated temp directory (not in `/etc/`, `/usr/`, or any system path).
+
+  For each sub-case, run `loopx install --no-install <source>`. Assert: (a) exit code 1, (b) the install fails preflight-atomically — `.loopx/` either does not exist or contains no `.loopx/ralph/` entry (no partial install was committed), and (c) stderr contains an error message identifying the failing non-script symlink (the test does not pin the exact wording, only that `ralph` and `README.md` are mentioned in the error context). For sub-case `(l-out-of-source)` specifically, the test must additionally verify that the controlled out-of-source target file still exists after the install fails — proving the rejection happened before any copy step touched it (and giving an extra signal that the test's preflight-traversal verification ran on a real existing file, not a broken target). **Parameterized across git and tarball sources** per SPEC 10.2 / 10.11. **`--no-install` per the section 4.10 auto-install-awareness rule.** A buggy implementation that validated only script-entry symlinks (T-INST-55h) and ignored non-script symlinked content would commit a workflow with a broken `README.md` reference. *(Spec 10.11, 10.7, 10.9, 10.2)*
+- **T-INST-55m**: Top-level workflow **directory** symlink resolving outside the install source root is rejected. SPEC 10.11's "Symlink targets must resolve to existing paths within the install source root" rule applies to all symlinks that are part of selected workflows, including the top-level workflow directory entry itself (not just symlinks nested inside a workflow). T-INST-55h sub-case (h-out-of-source) covers a **script-entry** symlink resolving outside the source root; this test extends that rule to a **top-level workflow directory** symlink. Multi-workflow source root containing a top-level symlink `alias -> /tmp/outside-workflow` where `/tmp/outside-workflow` is created outside the install source root and contains `index.sh` (so the symlink target itself qualifies as a workflow shape — proving the test isolates "out-of-source" rejection rather than "target is not a workflow" classification skip). Run `loopx install --no-install <source>` (no `-w`, so all qualifying workflows would be installed). Assert: (a) exit code 1, (b) the install fails preflight-atomically — `.loopx/alias/` does not exist (no partial install was committed), and (c) stderr contains an error message identifying the failing top-level workflow symlink `alias`. A buggy implementation that validated script-entry symlinks (T-INST-55h sub-case h-out-of-source) but skipped validation for top-level workflow-directory symlinks would commit `.loopx/alias/` containing arbitrary out-of-source content, defeating the SPEC 10.11 source-containment guarantee. **Parameterized across git and tarball sources** per SPEC 10.2 / 10.11. For the tarball source, the test creates the symlink during tarball construction (e.g., `tar` preserves symlinks); for git, the symlink is committed as a symlink object via standard git mechanisms. **`--no-install` per the section 4.10 auto-install-awareness rule.** *(Spec 10.11, 10.7, 10.9, 10.2)*
+- **T-INST-55n**: Symlinked workflow content whose target is **inside the install source root** but **outside the selected workflow** is materialized into the destination, while the source-root support directory holding the target is itself **not** copied. SPEC 10.11 says symlink targets must resolve within the **install source root** — not within the workflow directory itself, and SPEC 10.3 says non-workflow source-root subdirectories are silently skipped (do not appear in the destination). The combination is non-trivial: a workflow can legitimately reference content from a sibling source-root support directory (e.g., a `shared/` directory of READMEs or assets), and the install must materialize that referenced content into the workflow's destination directory while still suppressing the support directory itself from `.loopx/`. T-INST-55j / T-INST-55k cover symlinks whose targets are inside the **workflow directory**; this test closes the gap for symlinks whose targets are inside the source root but **outside** the workflow directory — a separate code path because the materialization walk must reach across the workflow boundary to the source root, not stay within the workflow. Two sub-cases, each tested independently (parameterized across git and tarball sources per SPEC 10.2 / 10.11):
+    - **(n-non-script-file)**: Source root contains a workflow directory `ralph/` (with a real `ralph/index.sh` so it qualifies) plus a sibling **support directory** `shared/` (containing the real file `shared/README.md` with deterministic content `"shared readme content"`). Inside `ralph/`, a non-script symlink `ralph/README.md -> ../shared/README.md` points up to the source-root sibling. Run `loopx install --no-install <source>`. Assert: (a) exit code 0, (b) `.loopx/ralph/` is committed and contains real `index.sh` and a real materialized `README.md` (`fs.lstat(...).isSymbolicLink()` is `false` for `.loopx/ralph/README.md`), (c) the materialized `README.md` content matches `shared/README.md` byte-for-byte (`"shared readme content"`), (d) `.loopx/shared/` does **not** exist — the source-root support directory holding the symlink target is not copied as a top-level entry in `.loopx/` (per SPEC 10.3 self-containment for non-workflow subdirectories), and (e) `.loopx/ralph/shared-assets` (or any other manifestation of the support directory inside the workflow) does not appear unless the test placed it there. The "shared" directory is referenced through a symlink but is not itself a workflow nor a workflow's content.
+    - **(n-non-script-directory)**: Source root contains a workflow directory `ralph/` (with a real `ralph/index.sh`) plus a sibling support directory `shared-assets/` containing real files `shared-assets/asset1.txt` (content `"asset-one"`) and `shared-assets/asset2.txt` (content `"asset-two"`). Inside `ralph/`, a top-level symlinked directory `ralph/assets -> ../shared-assets/` points up to the source-root sibling. Run `loopx install --no-install <source>`. Assert: (a) exit code 0, (b) `.loopx/ralph/assets` is a **real directory** (`fs.lstat(...).isSymbolicLink()` is `false`) containing real files `asset1.txt` and `asset2.txt` with content `"asset-one"` and `"asset-two"` respectively, and (c) `.loopx/shared-assets/` does **not** exist as a top-level destination entry — the source-root support directory is not copied as a top-level workflow.
+
+    Additionally for both sub-cases, run a `-w ralph` selective-install variant (`loopx install --no-install -w ralph <source>`) and assert the same destination shape — proving the cross-workflow-to-source-root materialization works under selective install too (SPEC 10.8 / 10.11 interaction). A buggy implementation that resolved symlink targets only relative to the workflow directory (rather than the install source root) would reject this fixture as "out-of-source" — incorrectly equating the workflow boundary with the source-root boundary. This test is critical because the SPEC 10.11 + SPEC 10.3 + SPEC 10.8 interaction has no other coverage: existing symlink tests have targets either inside the workflow itself (T-INST-55j / T-INST-55k) or strictly outside the source root (T-INST-55h / T-INST-55l / T-INST-55m), but neither exercises the legitimate "in-source-root, out-of-workflow" middle ground that SPEC 10.11 explicitly permits. **Parameterized across git and tarball sources** per SPEC 10.2 / 10.11. **`--no-install` per the section 4.10 auto-install-awareness rule.** *(Spec 10.11, 10.3, 10.8, 10.2)*
+
+- **T-INST-55o**: Install-time symlink **alias-name validation** uses the alias's own name, not the target's. SPEC 10.11 says install-time discovery follows symlinks under the same entry-type policy as runtime, and that names are derived from the symlink entry's own name. Combined with SPEC 10.4's name-restriction rule (which applies to install-time validation), this means a symlink alias whose **own** name is invalid must fail install, even when the target's basename is valid (and vice-versa for the runtime counterparts at T-DISC-40c / T-DISC-40d / T-DISC-40h / T-DISC-40i). The install-source-symlink policy on the negative side is currently uncovered. Two sub-cases, each tested independently:
+    - **(o-workflow-alias-bad)**: Multi-workflow source root containing a real workflow directory `internal/good-workflow/` (with `index.sh`) and a top-level **invalid-named** symlink `-bad-alias -> internal/good-workflow/`. The alias's own name (`-bad-alias`) violates SPEC 5.3's name pattern (leading `-`); the target's basename (`good-workflow`) is valid. Run `loopx install --no-install <source>` (no `-w`, so all qualifying workflows including the symlinked alias would otherwise be installed). Assert: (a) exit code 1 with a name-restriction error identifying `-bad-alias` (not the target basename), (b) `.loopx/-bad-alias/` does not exist, and (c) per atomicity (SPEC 10.7) no other workflow is committed either when the install fails preflight. This is the install-time counterpart to T-DISC-40c (run-mode runtime).
+    - **(o-script-alias-bad)**: Single-workflow source whose root contains a workflow directory `ralph/` (with a real `ralph/index.sh`) and a top-level invalid-named **script** symlink `ralph/-bad.sh -> /<source-root>/lib/valid-helper.sh` (where the target file exists in the source root and has a valid basename). The script alias's own basename (`-bad`) violates SPEC 5.3; the target's basename (`valid-helper`) is valid. Run `loopx install --no-install <source>`. Assert: (a) exit code 1 with a name-restriction error identifying `-bad.sh` in the `ralph` workflow (not the target's basename), (b) `.loopx/ralph/` is not committed (atomic preflight failure). This is the install-time counterpart to T-DISC-40d (run-mode runtime).
+
+  Together with the runtime counterparts (T-DISC-40c / T-DISC-40d for invalid alias, T-DISC-40h / T-DISC-40i for valid-alias-bad-target), this closes the install-time symlink-alias-name validation surface. A buggy implementation that derived names from target basenames at install time (rather than from the symlink entry's own name per SPEC 10.11) would either accept this install (deriving the valid target basename and failing assertion (a)), or fire under the wrong path with the wrong identifier in the error message. **Parameterized across git and tarball sources** per SPEC 10.2 / 10.11. **`--no-install` per the section 4.10 auto-install-awareness rule.** *(Spec 10.11, 10.4, 5.3, 10.7)*
+- **T-INST-55p**: Install-time symlink **entry-type policy** rejects non-workflow / non-script targets uniformly with runtime. SPEC 10.11 explicitly says install-time discovery follows symlinks under the **same entry-type policy as runtime** (SPEC 5.1) — symlinks to non-directory targets at the workflow level, or symlinks to non-file targets at the script level, do not qualify as workflows or scripts respectively. T-DISC-40j / T-DISC-40k cover the runtime side (silently ignored at runtime); the install-time entry-type-mismatch surface is uncovered. Two sub-cases, each tested independently:
+    - **(p-workflow-symlink-to-file)**: Source root containing a real workflow directory `ralph/` (with `index.sh`, valid) and a top-level symlink `notaworkflow -> README.md` where `README.md` is a real **regular file** in the source root with text content. The symlink resolves to a file, not a directory, so it does not qualify as a workflow per SPEC 5.1's entry-type policy. Run `loopx install --no-install <source>` (no `-w`). Assert: (a) exit code 0, (b) `.loopx/ralph/` is committed with `index.sh`, (c) `.loopx/notaworkflow` does **not** exist as a workflow at the destination (the symlink-to-file is silently skipped during workflow classification, same as T-DISC-40j at runtime), and (d) stderr emits no error or warning about `notaworkflow` (the entry-type-mismatch is not a name-restriction failure or a symlink-target-resolution failure — it is a non-workflow that gets silently skipped per SPEC 10.3 / 5.1).
+    - **(p-script-symlink-to-directory)**: Single-workflow source where workflow `ralph/` contains a real `ralph/index.sh` (the workflow definitely qualifies) and a top-level symlink `ralph/notascript.sh -> docs/` where `docs/` is a real **directory** inside the workflow with non-script content (e.g., `ralph/docs/note.md` containing the deterministic byte-string `"docs note content"`). The symlink resolves to a directory, not a file, so it does not qualify as a script per SPEC 5.1's entry-type policy. Run `loopx install --no-install <source>`. Assert: (a) exit code 0, (b) `.loopx/ralph/` is committed and contains `index.sh`, (c) the `notascript` script does **not** appear as a discoverable script — verified by `loopx run -n 1 "ralph:notascript"` failing with a missing-script error (mirroring T-DISC-40k at runtime), (d) `.loopx/ralph/notascript.sh` exists, is a **real directory** (`fs.lstat(...).isSymbolicLink()` is `false` and `fs.lstat(...).isDirectory()` is `true`), and contains `note.md` with byte-for-byte content `"docs note content"` matching the source `docs/` target — per SPEC 10.11's "Symlinked non-script files or directories inside a selected workflow's copied content are likewise materialized as real files or directories" rule (the entry is not classified as a script, but it is still a symlinked directory inside a selected workflow's copied content and must be materialized; this is the same rule pinned down at T-INST-55k for the symlinked-non-script-directory branch generally, applied here to the specific case where the symlink's name shape *would* satisfy script-naming if the entry-type test passed), and (e) stderr emits no name-restriction or entry-type warning. A buggy implementation that conflated "not classified as a script" with "skip from copy" would either omit `.loopx/ralph/notascript.sh` entirely (failing assertion (d)) or preserve the symlink unmaterialized (failing the `isSymbolicLink()` half of (d)).
+
+  Together with the runtime counterparts (T-DISC-40j workflow-symlink-to-file, T-DISC-40k script-symlink-to-directory), this closes the install-time entry-type-policy parity surface. SPEC 10.11's "same entry-type policy as runtime" clause must hold uniformly across both sub-cases. **Parameterized across git and tarball sources** per SPEC 10.2 / 10.11. **`--no-install` per the section 4.10 auto-install-awareness rule.** *(Spec 10.11, 5.1, 10.3)*
+- **T-INST-55q**: Install-time symlink alias-name validation uses the alias's own name on the **positive** path — a valid alias name with a target whose basename is invalid still installs successfully. SPEC 10.11 says install-time discovery follows symlinks under the same entry-type policy as runtime, and that names are derived from the symlink entry's own name, not the target's basename. T-INST-55o covers the negative side (invalid alias name → install fails), but the positive symmetry — that an invalid **target** basename is irrelevant when the alias name itself is valid — is uncovered on the install-time surface (T-DISC-40h / T-DISC-40i are the runtime counterparts). A buggy implementation that derived names from target basenames at install time would fail this test in addition to T-INST-55o. Two sub-cases, each tested independently:
+    - **(q-workflow-alias-good-target-bad)**: Before constructing the install source, the test creates a real workflow directory at an absolute path **outside the install source root** with an invalid basename (e.g., `<test-isolated-tmp>/-bad-real-workflow/` containing `index.sh`). The install source root contains a top-level symlink `goodalias -> <test-isolated-tmp>/-bad-real-workflow/`. *(Note: the symlink target is outside the install source root and would normally be rejected by SPEC 10.11's "Symlink targets must resolve to existing paths within the install source root" rule. To keep this test focused on the alias-name-positive-path question rather than the source-root-resolution rule, place the real workflow **inside** the install source root under a hidden support subdirectory: e.g., source root contains `internal/-bad-real-workflow/index.sh` and a top-level symlink `goodalias -> internal/-bad-real-workflow/`. The target's basename `-bad-real-workflow` is invalid, but the symlink resolves inside the source root, satisfying SPEC 10.11's source-containment rule. The source root also contains a real workflow directory `ralph/index.sh` so the source is unambiguously multi-workflow.)* Run `loopx install --no-install <source>` (no `-w`). Assert: (a) exit code 0, (b) `.loopx/goodalias/` is committed and contains `index.sh` with the materialized target's content, (c) `.loopx/ralph/` is also committed with `index.sh`, (d) `.loopx/-bad-real-workflow/` does not exist as a top-level destination (the source-root support subdirectory `internal/` and its target are not copied as workflows — only the symlink alias materializes), and (e) stderr emits no name-restriction warning for either `goodalias` or `-bad-real-workflow`. This is the install-time counterpart to T-DISC-40h.
+    - **(q-script-alias-good-target-bad)**: Source workflow `ralph/` contains a real `ralph/index.sh` and a real helper script with an invalid basename inside a workflow-internal support directory (e.g., `ralph/internal/-bad-real-script.sh` with executable bash content `#!/bin/bash` and a marker write). The workflow also contains a script symlink `ralph/goodcheck.sh -> internal/-bad-real-script.sh` (relative path, resolving inside the workflow). Run `loopx install --no-install <source>`. Assert: (a) exit code 0, (b) `.loopx/ralph/` is committed and contains `index.sh` and `goodcheck.sh` (`goodcheck.sh` is materialized as a real file with the symlink target's content — `fs.lstat(...).isSymbolicLink()` is `false`), (c) the installed workflow is runnable via `loopx run -n 1 "ralph:goodcheck"` (the script is discovered using the alias basename `goodcheck`, not the target basename `-bad-real-script`), and (d) stderr emits no name-restriction warning for either `goodcheck.sh` or `-bad-real-script.sh`. This is the install-time counterpart to T-DISC-40i. The fixture places the bad-named target inside the workflow's own subdirectory (rather than outside the source root) so the test isolates the alias-name positive-path question from SPEC 10.11's source-containment rule; the workflow-internal support file is not classified as a script (install validation is non-recursive within workflows per T-INST-64a / T-INST-64d), so its invalid basename is never validated.
+  
+  Together with T-INST-55o (negative: invalid alias rejects), the runtime counterparts T-DISC-40h / T-DISC-40i (valid alias good target — basename ignored), and T-DISC-40c / T-DISC-40d (invalid alias name rejects at runtime), this closes the install-time alias-name-validation parity surface across both alias-name validity polarities. **Parameterized across git and tarball sources** per SPEC 10.2 / 10.11. **`--no-install` per the section 4.10 auto-install-awareness rule.** *(Spec 10.11, 10.4, 5.3, 10.3)*
+- **T-INST-55r**: Install-time same-base-name script collision fires when one of the colliding scripts is a symlink. SPEC 10.4 / 10.11 say install-time validation uses the same discovery rules as runtime (SPEC 5.1 / 5.2), and SPEC 10.11 says install-time discovery follows symlinks under the same entry-type policy as runtime. T-DISC-40e covers the runtime side (symlinked script participates in same-base-name collision detection — runtime fatal); T-INST-62 / T-INST-62a cover install-time same-base-name collisions for **regular** files; the install-time **symlinked-script** participation in same-base-name collision detection is uncovered. A buggy implementation that resolved symlinks during install-time discovery but skipped them during install-time same-base-name collision evaluation would pass T-DISC-40e and T-INST-62 / T-INST-62a yet fail to detect this collision at install time. Source workflow `ralph/` contains a real `ralph/check.sh` (with marker-write content), a real workflow-internal helper file `ralph/lib/helper.ts` (also with deterministic content — placed inside a subdirectory so it is not itself a top-level script), and a top-level script symlink `ralph/check.ts -> lib/helper.ts` (relative path, resolving inside the workflow). The real `check.sh` and the symlinked `check.ts` share the base name `check`, the same way as T-DISC-40e at runtime. Run `loopx install --no-install <source>`. Assert: (a) exit code 1, (b) `.loopx/ralph/` does not exist (preflight-atomic per SPEC 10.7), and (c) stderr surfaces a same-base-name collision error that names both the regular entry `check.sh` and the symlinked entry `check.ts` in the `ralph` workflow. **Parameterized across git and tarball sources** per SPEC 10.2 / 10.11. **`--no-install` per the section 4.10 auto-install-awareness rule.** *(Spec 10.11, 10.4, 5.1, 5.2, 10.7)*
+- **T-INST-55s**: Top-level workflow-symlink **broken** target and **cyclic** target are rejected preflight-atomically. T-INST-55m covers a top-level workflow-directory symlink resolving outside the install source root; the broken-target and cycle branches of the same SPEC 10.11 rule ("Symlink targets must resolve to existing paths within the install source root") on top-level workflow-directory symlinks are uncovered. (T-INST-55h covers script-entry symlinks with broken / cycle / out-of-source targets; T-INST-55l covers non-script symlinks inside a workflow with the same three classes; T-INST-55m covers top-level workflow symlinks for the out-of-source class only.) Two sub-cases, each tested independently. The source root in both sub-cases also contains a real workflow directory `ralph/` (with `index.sh`) so the source is unambiguously multi-workflow.
+    - **(s-broken)**: Source root contains a top-level symlink `alias -> missing-target` where `missing-target` does not exist anywhere on disk (neither inside the source root nor outside). Run `loopx install --no-install <source>`. Assert: (a) exit code 1, (b) the install fails preflight-atomically — neither `.loopx/alias/` nor `.loopx/ralph/` is committed, and (c) stderr contains an error message identifying the failing top-level workflow symlink `alias` (the test does not pin exact wording, only that `alias` is mentioned and that the failure is symlink-target related — broken / unresolved).
+    - **(s-cycle)**: Source root contains three top-level symlinks `alias -> a`, `a -> b`, `b -> a` — a cycle in the symlink chain. The chain never resolves to a real directory. Run `loopx install --no-install <source>`. Assert: (a) exit code 1, (b) the install fails preflight-atomically — none of `.loopx/alias/`, `.loopx/a/`, `.loopx/b/`, or `.loopx/ralph/` is committed, and (c) stderr contains an error message identifying the failing top-level workflow symlink (the test does not pin which of `alias` / `a` / `b` is named first, only that at least one is named and the failure is symlink-cycle related). The test must also verify the implementation does not infinite-loop on the cycle (the install command must exit within a reasonable timeout — e.g., 10 seconds — proving symlink-cycle detection ran rather than the implementation looping until OS limits intervene).
+
+  Together with T-INST-55m (top-level workflow symlink, out-of-source target — already covered) and T-INST-55h sub-cases (script-entry symlinks: broken, cycle, out-of-source), this closes the SPEC 10.11 broken / cycle / out-of-source rejection rule across the three symlink-entry kinds: script entries (T-INST-55h), non-script content inside workflows (T-INST-55l), and top-level workflow directories (T-INST-55m + this test). A buggy implementation that handled out-of-source rejection on top-level workflow symlinks (passing T-INST-55m) but skipped broken-target or cycle detection on the same code path would fail this test. **Parameterized across git and tarball sources** per SPEC 10.2 / 10.11. **`--no-install` per the section 4.10 auto-install-awareness rule.** *(Spec 10.11, 10.7, 10.9, 10.2)*
+- **T-INST-55t**: Bad symlinks in **source-root support directories** are ignored under both full-multi-workflow install and `-w` selective install. SPEC 10.11 says "When `-w <name>` / `--workflow <name>` is used, only symlinks that are part of the selected workflow are validated and materialized. Symlinks in unselected workflow directories or source-root support directories are ignored, consistent with the selective validation rule in section 10.8." For full multi-workflow installs (no `-w`), SPEC 10.3's source-root-self-containment rule says non-workflow source-root directories are silently skipped — so symlinks in source-root support directories are also not validated or materialized at the destination. T-INST-55i covers bad symlinks in **unselected sibling workflow directories** under `-w`; the **source-root support-directory** branch is uncovered for both invocations (full and `-w`). A buggy implementation that walked source-root support directories during preflight (e.g., to compute the staging copy plan) and validated their symlinks would fail this test even though it passes T-INST-55i. Source root contains:
+  - A real workflow directory `ralph/` (with `index.sh`).
+  - A real workflow directory `other/` (with `index.sh`).
+  - A source-root support directory `docs/` containing three sub-cases of bad symlinks side-by-side: `docs/broken-link -> nonexistent-target` (broken), `docs/cycle-a -> cycle-b`, `docs/cycle-b -> cycle-a` (cycle), and `docs/out-of-source -> /tmp/<test-isolated-out-of-source>/some-file` where the out-of-source target is a real, existing file outside the install source root (verified to exist via `fs.realpath` before invoking install — discriminates the out-of-source class from the broken class). Place all three classes inside `docs/` simultaneously so the test exercises all three SPEC 10.11 failure-class branches in the source-root-support-directory code path together.
+  
+  Two invocations:
+    - **(t-full)**: Run `loopx install --no-install <source>` (no `-w`). Assert: (a) exit code 0 (the source-root support directory is silently skipped per SPEC 10.3, so its bad symlinks are never validated), (b) `.loopx/ralph/` and `.loopx/other/` are committed with their respective `index.sh` files, (c) `.loopx/docs/` does not exist as a top-level destination (per SPEC 10.3 self-containment, source-root support directories are not copied), (d) `.loopx/ralph/docs/` and `.loopx/other/docs/` likewise do not exist (the support directory was not migrated into either workflow), and (e) stderr emits no symlink-target-resolution error or warning identifying any of `broken-link`, `cycle-a`, `cycle-b`, or `out-of-source`.
+    - **(t-selective)**: Run `loopx install --no-install -w ralph <source>`. Assert: (a) exit code 0, (b) `.loopx/ralph/` is committed with `index.sh`, (c) `.loopx/other/` does not exist (selective install excludes other workflows), (d) `.loopx/docs/` does not exist, and (e) stderr emits no symlink-target-resolution error or warning. The selective-validation rule in SPEC 10.8 / 10.11 limits validation to the selected workflow only; the source-root support directory is not part of the selected workflow.
+  
+  Together with T-INST-55i (bad symlinks in unselected sibling workflow directories under `-w`, ignored), this closes the "bad symlinks outside the validated scope are ignored" surface across both off-scope locations (sibling workflow dirs vs. source-root support dirs) and both invocation modes (full and `-w`). **Parameterized across git and tarball sources** per SPEC 10.2 / 10.11. **`--no-install` per the section 4.10 auto-install-awareness rule.** *(Spec 10.11, 10.8, 10.3, 10.2)*
+
+This block does **not** affect runtime symlink coverage or install-destination-collision symlink coverage (T-INST-70 and related), which remain separately covered.
 
 #### Selective Workflow Installation
 
@@ -1443,15 +2902,15 @@ All install tests use local servers (HTTP, file:// git repos). No network access
 - **T-INST-60g**: With `-w`, the selected workflow's own invalid script names are still fatal. Multi-workflow source where `broken/` contains `-bad.sh` (invalid script name) and `ralph/` is valid (contains `index.sh`). `loopx install -w broken <source>` → exits with code 1. T-INST-60a proves unselected siblings' invalid names are ignored; this proves the selected workflow itself is not exempt from install-time validation under `-w`. *(Spec 10.8, 10.4)*
 - **T-INST-60h**: With `-w`, the selected workflow's own same-base-name collisions are still fatal. Multi-workflow source where `broken/` contains `check.sh` and `check.ts` (same base name, different extensions) and `ralph/` is valid (contains `index.sh`). `loopx install -w broken <source>` → exits with code 1. T-INST-60e proves unselected siblings' collisions are ignored; this proves the selected workflow itself is still checked. *(Spec 10.8, 10.4)*
 - **T-INST-60i**: With `-w`, the selected workflow's own version mismatch is still a blocking error. Multi-workflow source where `ralph/` contains `index.sh` plus a `package.json` declaring a `loopx` version range not satisfied by the running version, and `other/` is valid (contains `index.sh`, no `package.json`). `loopx install -w ralph <source>` → exits with code 1. T-INST-60b proves unselected siblings' version mismatches are ignored; this proves the selected workflow's version declaration is still enforced under `-w`. *(Spec 10.8, 10.6)*
-- **T-INST-60j**: With `-w -y`, the selected workflow's version mismatch is overridden. Same source as T-INST-60i. `loopx install -w -y ralph <source>` succeeds. Assert `.loopx/ralph/` is created and contains `index.sh` and the workflow's `package.json` with its version declaration preserved. *(Spec 10.8, 10.6)*
+- **T-INST-60j**: With `-w -y`, the selected workflow's version mismatch is overridden. Same source as T-INST-60i. `loopx install -w ralph -y --no-install <source>` succeeds (the command line is written with `-w ralph` separated from `-y` so that `ralph` is unambiguously the `-w` operand and not treated as a `-y` operand or positional). Assert `.loopx/ralph/` is created and contains `index.sh` and the workflow's `package.json` with its version declaration preserved. **`--no-install` is included per the section 4.10 auto-install-awareness rule** — the workflow has a top-level `package.json`, so auto-install would otherwise fire after the `-y` override unblocks the commit; this test's contract is the `-w -y` version-mismatch-override behavior. *(Spec 10.8, 10.6)*
 - **T-INST-60k**: With `-w`, the selected workflow's own destination collision is still a blocking error. Multi-workflow source where `ralph/` contains `index.sh` and `other/` is valid (contains `index.sh`). `.loopx/ralph/` already exists as a workflow (contains at least one top-level script file). `loopx install -w ralph <source>` → exits with code 1. T-INST-60c proves unselected siblings' destination collisions are ignored; this proves the selected workflow's collision is still enforced under `-w`. *(Spec 10.8, 10.5)*
-- **T-INST-60l**: With `-w -y`, the selected workflow's destination collision is overridden. Same setup as T-INST-60k. `loopx install -w -y ralph <source>` succeeds. Assert `.loopx/ralph/` contains the new workflow content from the source (not the old content). `.loopx/other/` does not exist — only the selected workflow is installed. *(Spec 10.8, 10.5)*
+- **T-INST-60l**: With `-w -y`, the selected workflow's destination collision is overridden. Same setup as T-INST-60k. `loopx install -w ralph -y <source>` succeeds (the command line is written with `-w ralph` separated from `-y` so that `ralph` is unambiguously the `-w` operand and not treated as a `-y` operand or positional). Assert `.loopx/ralph/` contains the new workflow content from the source (not the old content). `.loopx/other/` does not exist — only the selected workflow is installed. *(Spec 10.8, 10.5)*
 - **T-INST-60p**: With `-w -y`, a non-workflow destination for the selected workflow still causes failure. Multi-workflow source where `ralph/` contains `index.sh` and `other/` is valid (contains `index.sh`). `.loopx/ralph` already exists but is not a workflow by structure (e.g., a plain file, an empty directory, or a symlink to a non-workflow target). `loopx install -w ralph -y <source>` → exits with code 1. The `-y` flag overrides workflow-path collisions and version mismatches, but does not override non-workflow destination paths — even on the selective `-w` code path. T-INST-60k/60l cover the `-w` collision path where the destination is a real workflow; T-INST-68/69/70a/70c cover non-workflow collision refusal on the generic (non-`-w`) path. This combination is worth testing because `-w` often gets its own code path. *(Spec 10.8, 10.5)*
-- **T-INST-60m**: With `-w`, selecting a workflow with an invalid name causes install to fail. Multi-workflow source contains `-bad-name/` (with `index.sh` — valid scripts but invalid workflow name) and `good/` (with `index.sh`). `loopx install -w -bad-name <source>` → exits with code 1. T-INST-60d proves an unselected invalid workflow name does not block `-w`; this proves the selected workflow's name is still validated even under `-w`. *(Spec 10.8, 5.3)*
+- **T-INST-60m**: With `-w`, selecting a workflow with an invalid name causes install to fail. Multi-workflow source contains `bad.name/` (with `index.sh` — valid scripts but invalid workflow name because `.` is not permitted by SPEC 5.3's `[a-zA-Z0-9_][a-zA-Z0-9_-]*` pattern) and `good/` (with `index.sh`). `loopx install -w bad.name <source>` → exits with code 1. T-INST-60d proves an unselected invalid workflow name does not block `-w`; this proves the selected workflow's name is still validated even under `-w`. The invalid name is deliberately chosen to **not** begin with `-` so that `-w bad.name` cannot be misread as `-w` consuming a hypothetical unrecognized flag — the test validates selected-workflow name validation, not flag-parsing edge cases. *(Spec 10.8, 5.3)*
 - **T-INST-60n**: `--workflow` long form exercises the same selective-validation semantics as `-w`. Multi-workflow source where `ralph/` is valid (contains `index.sh`) and `broken/` has an invalid script name (e.g., `broken/-bad.sh`). `.loopx/` initially empty. `loopx install --workflow ralph <source>` succeeds and `.loopx/ralph/` is created — the invalid script name in `broken/` is not evaluated. This mirrors T-INST-60a but uses the `--workflow` long form to verify that selective validation is not inadvertently tied to the short `-w` parsing path. *(Spec 10.8, 10.4, 4.2)*
 - **T-INST-60o**: With `-w`, selecting a subdirectory that does not qualify as a workflow is an error. Multi-workflow source contains `good/index.sh` and `legacy/package.json` (with `{ "main": "src/run.js" }`) plus `legacy/src/run.js`, but no top-level script files inside `legacy/`. `loopx install -w legacy <source>` → exits with code 1 (named workflow does not exist in source). `legacy/` is not a workflow because it has no top-level supported-extension files — the `-w` flag does not cause loopx to relax workflow detection rules. This is the selective-install counterpart to T-INST-55e (which covers the same legacy subdirectory being silently skipped during full multi-workflow install). *(Spec 10.8, 10.3)*
 - **T-INST-60q**: With `-w`, the selected workflow's own `package.json` with invalid JSON emits a single non-fatal warning and the install still succeeds. Multi-workflow source where `ralph/` contains `index.sh` plus a `package.json` with invalid JSON content (e.g., `{broken`), and `other/` is valid (contains `index.sh`, no `package.json`). `loopx install -w ralph <source>` → exit code 0. Assert: (a) stderr contains exactly one `package.json` parse-failure warning for `ralph`, (b) `.loopx/ralph/` is installed and contains both `index.sh` and the broken `package.json` (file is preserved as-is), and (c) `.loopx/other/` does not exist. T-INST-75 proves invalid JSON emits a non-fatal warning on the generic install path; T-INST-60f proves the warning is suppressed for unselected siblings under `-w`; this test pins down that the selected workflow under `-w` still receives the normal non-fatal warning behavior — the `-w` code path does not accidentally promote the warning to a fatal error or suppress it entirely for the selected workflow. *(Spec 10.8, 10.6, 3.2)*
-- **T-INST-60r**: With `-w`, the selected workflow's own unreadable `package.json` emits a single non-fatal warning and the install still succeeds. Same structure as T-INST-60q, but `ralph/package.json` is set to mode 000 (unreadable) instead of containing invalid JSON. **Source must be a tarball** (or another non-git source path), since Git does not reliably preserve mode 000 file permissions across clone. `loopx install -w ralph <tarball-url>` → exit code 0. Assert: (a) stderr contains exactly one `package.json` read-failure warning for `ralph`, (b) `.loopx/ralph/` is installed and contains `index.sh` and the unreadable `package.json`, and (c) `.loopx/other/` does not exist. This is the unreadable-file counterpart to T-INST-60q (invalid JSON) — T-INST-74 covers the generic path; this test covers the selective `-w` path. **Conditional on `process.getuid() !== 0`.** *(Spec 10.8, 10.6, 3.2)*
+- **T-INST-60r**: With `-w`, the selected workflow's own unreadable `package.json` emits a single non-fatal warning and the install still succeeds. Same structure as T-INST-60q, but `ralph/package.json` is set to mode 000 (unreadable) instead of containing invalid JSON. **Source must be a tarball** (or another non-git source path), since Git does not reliably preserve mode 000 file permissions across clone. `loopx install -w ralph <tarball-url>` → exit code 0. Assert: (a) stderr contains exactly one `package.json` read-failure warning for `ralph`, (b) `.loopx/ralph/` is installed and contains `index.sh` and a `package.json` entry at `.loopx/ralph/package.json` (the file's committed permission mode is **not** asserted, for the same reason as T-INST-74a — SPEC 10.6 / 3.2 / 10.7 require the warning and the install to proceed but do not require destination mode 000 preservation), and (c) `.loopx/other/` does not exist. This is the unreadable-file counterpart to T-INST-60q (invalid JSON) — T-INST-74 covers the generic path; this test covers the selective `-w` path. **Conditional on `process.getuid() !== 0`.** *(Spec 10.8, 10.6, 3.2)*
 - **T-INST-60s**: With `-w`, the selected workflow's own `package.json` with an invalid semver range for `loopx` emits a single non-fatal warning and the install still succeeds. Same structure as T-INST-60q, but `ralph/package.json` contains valid JSON with an invalid semver range (e.g., `{ "dependencies": { "loopx": "not-a-range!!!" } }`) instead of invalid JSON. `loopx install -w ralph <source>` → exit code 0. Assert: (a) stderr contains exactly one invalid-semver warning for `ralph`, (b) `.loopx/ralph/` is installed and contains `index.sh` and the `package.json` with its original (invalid) range preserved, and (c) `.loopx/other/` does not exist. This is the invalid-semver counterpart to T-INST-60q (invalid JSON) and T-INST-60r (unreadable) — T-INST-76 covers the generic path; this test covers the selective `-w` path. Together, T-INST-60q/60r/60s prove the `-w` code path preserves the non-fatal-warning behavior across all three `package.json` failure branches for the selected workflow. *(Spec 10.8, 10.6, 3.2)*
 
 #### Install-time Validation
@@ -1464,12 +2923,15 @@ All install tests use local servers (HTTP, file:// git repos). No network access
 - **T-INST-63b**: Install rejects a workflow name containing `:`. Source whose derived workflow name includes a colon (e.g., a tarball archive named `my:workflow.tar.gz` containing root-level `index.sh`). `loopx install <source>` → exits with code 1. The `:` is the reserved target delimiter and is explicitly disallowed in names. This mirrors runtime discovery coverage (T-DISC-32) at the install-time validation code path. *(Spec 10.4, 5.3)*
 - **T-INST-63c**: Install rejects a script base name containing `:`. Single-workflow source containing a script file with `:` in its base name (e.g., `check:ready.sh` alongside a valid `index.sh`). `loopx install <source>` → exits with code 1. This mirrors runtime discovery coverage (T-DISC-31) at the install-time validation code path. *(Spec 10.4, 5.3)*
 - **T-INST-63d**: Numeric script names are valid at install time. Single-workflow source containing `index.sh`, `1start.sh`, and `42.sh`. `loopx install <source>` succeeds. Assert `.loopx/<repo-name>/` contains all three scripts. This is the install-time positive counterpart to T-DISC-30a/30b (digit-start and all-digit script names valid at runtime discovery) — runtime naming allows these, but install-time script-name validation is only covered explicitly with negative cases (T-INST-61, T-INST-63c) without a symmetric positive case for numeric names. *(Spec 10.4, 5.3)*
+- **T-INST-63g**: Underscore-prefix script base name is valid at install time. SPEC 10.4 / 5.3's name pattern accepts `_` as the leading character. Single-workflow source containing `index.sh` and `_check.sh` (a non-`index` script with a leading underscore). `loopx install <source>` succeeds. Assert: (a) exit code 0, (b) `.loopx/<repo-name>/_check.sh` is present with its original name, and (c) the installed workflow is runnable via `loopx run -n 1 "<repo-name>:_check"`. This is the install-time positive counterpart to T-DISC-30e (runtime), closing the underscore-prefix script-name coverage gap on the install-time name-validation code path. T-INST-63d already covers digit-first and all-digit script names at install time; this test extends that pattern to the underscore-prefix branch, exercising the same `_`-as-first-character branch of the name-pattern validator that workflow-name coverage exercises via T-DISC-26 (`_underscore`). *(Spec 10.4, 5.3, 2.1)*
+- **T-INST-63f**: Uppercase workflow and script names are valid at install time. Multi-workflow source whose derived workflow name is `MyWorkflow` (directory `MyWorkflow/` at the source root), containing `MyWorkflow/index.sh` and `MyWorkflow/CheckReady.sh` (uppercase-starting script base name alongside the `index` entry). `loopx install <source>` succeeds. Assert: (a) exit code 0, (b) the installed workflow directory is exactly `.loopx/MyWorkflow/` (case-preserving, not lowercased), (c) both `.loopx/MyWorkflow/index.sh` and `.loopx/MyWorkflow/CheckReady.sh` are present with their original case, and (d) the installed workflow is runnable via the case-preserving target `loopx run -n 1 "MyWorkflow:CheckReady"`. This is the install-time positive counterpart to T-DISC-30c / T-DISC-30d — the name-pattern validator at install time (SPEC 10.4) must accept the same uppercase forms that runtime discovery (SPEC 5.3) accepts. An implementation that lowercased derived workflow names during install-time validation would install to `.loopx/myworkflow/` and break the case-preserving guarantee. *(Spec 10.4, 5.3)*
 - **T-INST-63e**: Install rejects a multi-workflow subdirectory name containing `:`. Multi-workflow source whose source root (after any wrapper-directory stripping) contains a subdirectory named with `:` (e.g., `foo:bar/index.sh`) alongside a valid sibling workflow (e.g., `other/index.sh`) and no root-level script files. `loopx install <source>` → exits with code 1 with a name-restriction error identifying the offending subdirectory name. Per the install atomicity rules (Spec 10.7), no workflows are written — assert `.loopx/foo:bar/` does not exist AND `.loopx/other/` does not exist. T-INST-63b covers the single-workflow tarball archive-name derivation path (archive name `my:workflow.tar.gz`); this test exercises the **second** install-time workflow name source — multi-workflow subdirectory-name derivation — ensuring ADR-0003's reserved-delimiter `:` rule fires on both derivation paths. A buggy implementation could reject `:` only in the archive-name path and silently install (or skip) a `:`-named subdirectory in the multi-workflow path. *(Spec 10.4, 10.3, 5.3, 10.7)*
 - **T-INST-64**: Missing `index` script is allowed at install time for single-workflow sources. A single-workflow source whose root contains `check.sh` but no `index.*` file. `loopx install <source>` succeeds. Assert the installed workflow is present under `.loopx/<repo-name>/` and contains `check.sh`. This explicitly covers the single-workflow classification path introduced by ADR-0003 — root-level script files make the source single-workflow, and missing `index` is still allowed. A bug could exist where a multi-workflow subdirectory can omit `index` but a single-workflow source incorrectly requires it. *(Spec 10.4, 10.3)*
 - **T-INST-64b**: Missing `index` script is allowed at install time for multi-workflow sources. Multi-workflow source with `tools/check.sh` (no `tools/index.*`) and `other/index.sh` (to force multi-workflow classification). `loopx install <source>` succeeds. Assert both `.loopx/tools/` and `.loopx/other/` are installed, and `.loopx/tools/` contains `check.sh`. This complements the single-workflow path (T-INST-64) — a bug could allow missing index in single-workflow sources but incorrectly require it in multi-workflow subdirectories. *(Spec 10.4, 10.3)*
 - **T-INST-64c**: Missing `index` script is allowed at install time for multi-workflow sources with `-w` scoping. Same source as T-INST-64b. `loopx install -w tools <source>` succeeds. Assert `.loopx/tools/` is installed and contains `check.sh`, and `.loopx/other/` does not exist. This covers the selective-install path for a workflow without an index script. *(Spec 10.4, 10.8)*
 - **T-INST-64a**: Install-time validation is non-recursive within a workflow. Single-workflow source has a top-level `index.ts` plus a nested `lib/` subdirectory containing `-bad.ts` (invalid script name) and both `check.sh` and `check.ts` (same-base-name collision). Install succeeds because nested files within a workflow are not discovered or validated as scripts — only top-level files are checked. Assert exit code 0 and that `.loopx/<repo-name>/lib/-bad.ts`, `.loopx/<repo-name>/lib/check.sh`, and `.loopx/<repo-name>/lib/check.ts` are all present in the installed workflow (copied as workflow content, not rejected as invalid scripts). *(Spec 10.4, 2.1)*
 - **T-INST-64d**: Install-time validation is non-recursive within workflows in a multi-workflow source. Multi-workflow source with two workflows: `ralph/index.sh` plus `ralph/lib/-bad.ts` (invalid script name) and `ralph/lib/check.sh` + `ralph/lib/check.ts` (same-base-name collision), and `other/index.sh` (a second workflow to force multi-workflow classification). Install succeeds because nested files within a workflow are not discovered or validated as scripts — only top-level files are checked. Assert exit code 0 and that `.loopx/ralph/lib/-bad.ts`, `.loopx/ralph/lib/check.sh`, and `.loopx/ralph/lib/check.ts` are all present in the installed workflow (copied as workflow content, not rejected as invalid scripts). This is the multi-workflow counterpart to T-INST-64a (which covers the single-workflow path). *(Spec 10.4, 2.1)*
+- **T-INST-64e**: Install copies workflow content that includes a top-level directory whose name shape matches a script extension, but does **not** discover or validate that directory as a script. SPEC 10.4 says install-time validation uses the same discovery rules as runtime (SPEC 5.1), and SPEC 5.1 requires scripts to be top-level **files** with supported extensions; a directory whose name happens to end in `.sh`/`.ts`/`.js`/`.jsx`/`.tsx` is not a file. Set up a single-workflow source whose root contains a valid `index.sh` (a real file) **plus** a top-level directory named `bad.name.ts/` (created with `mkdir -p bad.name.ts`, optionally containing inner content e.g., `bad.name.ts/notes.md`). The directory name `bad.name.ts` would be invalid as a script base name (contains `.`) if it were treated as a script, so any implementation that wrongly classifies it as a script will surface as an install failure. Run `loopx install --no-install <source>` (the workflow has no top-level `package.json`, but `--no-install` is included for forward-compatibility under the section 4.10 auto-install-awareness rule). Assert: (a) exit code 0, (b) `.loopx/<name>/index.sh` exists (classified and copied as a script), (c) `.loopx/<name>/bad.name.ts/` exists as a directory and `.loopx/<name>/bad.name.ts/notes.md` exists byte-for-byte (the entire entry is preserved as workflow content under SPEC 10.3's self-containment rule), (d) stderr contains no install-time validation warning for `bad.name.ts` (the directory was not validated as a script — install validation is non-recursive within workflows per T-INST-64a/T-INST-64d, and the top-level directory was not classified as a script in the first place because it is not a file), and (e) at runtime, `loopx run -h` lists `<name>` with `index` as its only discovered script — `bad.name.ts` does not appear. A buggy implementation that walked workflow contents by name pattern without checking entry type would wrongly validate `bad.name.ts` as a script and fail install with an invalid-script-name error. This is the install-time counterpart to T-DISC-09b (runtime non-discovery of directory-shaped script-named entries). *(Spec 10.3, 10.4, 5.1, 2.1)*
 - **T-INST-52b**: Multi-workflow source with `ralph/index.sh`, `ralph/eslint.config.js`, and `other/index.sh` → install fails because every top-level file with a supported extension inside a workflow directory is a discovered script, and `eslint.config` violates the script name restriction `[a-zA-Z0-9_][a-zA-Z0-9_-]*` (the dot is not allowed). Assert exit code 1 and that the error references the invalid script name. This is the install-time mirror of T-DISC-15a / T-DISC-15b, which test the same "no opt-out" rule at runtime discovery — a buggy installer could special-case config/helper-style files during workflow-directory scanning and still pass the current suite. *(Spec 2.1, 5.3, 10.4)*
 
 #### Collision Handling
@@ -1483,20 +2945,21 @@ All install tests use local servers (HTTP, file:// git repos). No network access
 - **T-INST-70**: Symlinked workflow collision: structural check follows the symlink target. `.loopx/foo` is a symlink pointing to a directory that contains at least one top-level file with a supported script extension. `loopx install <source>` where the source contains a workflow named `foo` → install refused with collision error. The structural check followed the symlink and found a workflow at the target. *(Spec 10.5)*
 - **T-INST-70b**: Symlinked workflow with `-y`: removes the symlink itself, not the target directory. `.loopx/foo` is a symlink pointing to a directory that qualifies as a workflow (contains a top-level script file). `loopx install -y <source>` where the source contains a workflow named `foo` → install succeeds. Assert: (a) `.loopx/foo` is now a regular directory (not a symlink) containing the new workflow content, and (b) the original symlink target directory still exists and is unmodified. *(Spec 10.5)*
 - **T-INST-70a**: Symlink-to-non-workflow collision refusal. `.loopx/foo` is a symlink whose target is a directory with no top-level script files (e.g., the target contains only `lib/helper.ts` nested in a subdirectory). `loopx install -y <source>` where the source contains a workflow named `foo` → install refuses with an error, even with `-y`. The structural check follows the symlink, finds the target is not a workflow (no top-level script files), and treats it as a non-workflow destination path. *(Spec 10.5)*
+- **T-INST-70e**: Broken-symlink collision — install refuses as non-workflow destination even with `-y`, and `-y` does not remove the broken symlink. Per SPEC 10.5, "Collision is determined by whether any filesystem entry (file, directory, or symlink) already exists at `.loopx/<workflow-name>`" — a broken symlink (dangling target) is a filesystem entry, so collision applies. And "Path exists but is not a workflow by structure ... : The install is refused with an error, even with `-y`. This prevents `-y` from accidentally deleting non-workflow data." A broken symlink cannot be a workflow by structure (it has no target directory), so `-y` must not replace it. Setup: create `.loopx/foo` as a symlink whose target does **not** exist (e.g., `ln -s /tmp/nonexistent-target/ /project/.loopx/foo`). Case A: run `loopx install <source>` (without `-y`) where the source contains a valid workflow named `foo`. Assert: (a) exit code 1 with a collision / non-workflow-destination error, (b) `.loopx/foo` is still the original broken symlink (symlink entry unchanged, target path still non-existent), and (c) no workflow content was written. Case B: run `loopx install -y <source>`. Assert the same three outcomes — `-y` must **not** treat a broken symlink as a replaceable entry, because a broken symlink is not a workflow by structure and SPEC 10.5 forbids `-y` from deleting non-workflow data. Together with T-INST-70/70a/70b/70c/70d (various symlink-to-something cases), this closes the "broken symlink" branch of symlink-based collision coverage — the symlink structural check follows symlinks per Spec 10.5, so a dangling target is observable as "the target does not qualify as a workflow" and must be refused. *(Spec 10.5)*
 - **T-INST-70c**: Symlink-to-file collision refusal. `.loopx/foo` is a symlink whose target is a regular file (not a directory). `loopx install -y <source>` where the source contains a workflow named `foo` → install refuses with an error, even with `-y`. A symlink to a file is a non-directory filesystem entry — it cannot be a workflow by structure (workflows are directories containing script files), so `-y` must not replace it. This completes the symlink/non-directory branch: T-INST-70/70b cover symlink-to-workflow-directory, T-INST-70a covers symlink-to-non-workflow-directory, and this test covers symlink-to-file. *(Spec 10.5)*
 - **T-INST-70d**: Symlink-to-structurally-valid-but-full-validation-invalid workflow is replaceable with `-y`. Create a directory outside `.loopx/` (e.g., `/tmp/invalid-workflow/`) that is structurally a workflow (contains at least one top-level file with a supported script extension, e.g., `index.sh`) but would fail full runtime validation — it contains a same-base-name collision (`check.sh` and `check.ts`) and an invalid script name (`-bad.sh`). Then symlink `.loopx/foo → /tmp/invalid-workflow/`. Run `loopx install -y <source>` where the source contains a valid workflow named `foo`. Assert: (a) exit code 0, (b) `.loopx/foo` is now a regular directory (symlink replaced) containing the new workflow content, and (c) the original symlink target directory `/tmp/invalid-workflow/` still exists and is unmodified (symlink itself was removed, not the target). T-INST-67a proves this "local structural check only" rule for regular-directory replacements, and T-INST-70b proves symlink-to-valid-workflow replaces; this test completes the coverage by proving the rule holds on the symlink path even when the target would fail full validation. *(Spec 10.5)*
 - **T-INST-71**: `-y` replaceability check is local to `.loopx/<workflow-name>` — broken siblings elsewhere under `.loopx/` do not affect collision evaluation. Set up: `.loopx/foo/` exists as a replaceable workflow (contains at least one top-level file with a supported script extension), and an unrelated sibling `.loopx/broken/` exists as a non-workflow directory (e.g., contains only a `README.md` and no script files). `loopx install -y <source>` where the source contains a valid workflow named `foo`. Assert: install succeeds and `.loopx/foo/` is replaced with the new workflow content. The structural check inspects only the target path `.loopx/foo/`, not the entire `.loopx/` tree — the broken sibling is irrelevant. *(Spec 10.5)*
 - **T-INST-71a**: `-y` replaceability check is local to `.loopx/<workflow-name>` — invalid sibling *workflows* elsewhere under `.loopx/` do not affect collision evaluation. Set up: `.loopx/foo/` exists as a replaceable workflow (contains `index.sh`), and `.loopx/broken/` exists as a workflow that would fail runtime validation (e.g., contains `check.sh` and `check.ts` — same-base-name collision, or `-bad.sh` — invalid script name). `loopx install -y <source>` where the source contains a valid workflow named `foo`. Assert: install succeeds and `.loopx/foo/` is replaced with the new workflow content. This strengthens T-INST-71 (which uses a non-workflow sibling) to prove that even invalid workflows elsewhere under `.loopx/` are ignored during collision evaluation — the install mechanism inspects only the target path. *(Spec 10.5)*
-- **T-INST-97**: Installing workflow `foo` succeeds when a non-workflow file `.loopx/foo.sh` exists. The collision check targets `.loopx/foo/` (directory), not `.loopx/foo.sh` (file) — they are different filesystem paths, so there is no collision. *(Spec 10.5)*
+- **T-INST-97c**: Installing workflow `foo` succeeds when a non-workflow file `.loopx/foo.sh` exists. The collision check targets `.loopx/foo/` (directory), not `.loopx/foo.sh` (file) — they are different filesystem paths, so there is no collision. *(Spec 10.5)*
 
 #### Version Checking on Install
 
 - **T-INST-72**: Workflow declares a loopx version range not satisfied by running version → install refused with error. *(Spec 10.6)*
-- **T-INST-73**: With `-y`, version mismatch is overridden and install proceeds. Version declaration preserved. *(Spec 10.6)*
-- **T-INST-72a**: Install-time version check for a no-index workflow with version mismatch. Single-workflow source containing `check.sh` (no `index` script) and a `package.json` declaring a loopx range not satisfied by the running version. `loopx install <source>` → exits with code 1 (version mismatch error). This combines the no-index install path (T-INST-64) with version checking (T-INST-72) — both covered separately, but the combination tests that the version check still runs for workflows that lack a default entry point. *(Spec 10.6, 10.4)*
-- **T-INST-73a**: Same setup as T-INST-72a with `-y`. `loopx install -y <source>` → exits 0. Assert the workflow is installed with `check.sh` and `package.json` version declaration preserved. This is the `-y` override counterpart to T-INST-72a. *(Spec 10.6, 10.4)*
-- **T-INST-74**: Workflow `package.json` unreadable → warning, install proceeds (no version validation). **Source must be a tarball** (or another non-git source path), since Git does not reliably preserve mode 000 file permissions across clone. **Conditional on `process.getuid() !== 0`.** *(Spec 10.6, 3.2)*
-- **T-INST-74a**: Install-time `package.json` unreadable warning for a no-index workflow. Single-workflow source containing `check.sh` (no `index.*` script) and a `package.json` file with mode 000 (unreadable). **Source must be a tarball** (or another non-git source path). Run `loopx install <tarball-url>`. Assert: (a) exit code 0, (b) stderr contains an unreadable-file warning for the workflow, and (c) the workflow is installed at `.loopx/<name>/` and contains `check.sh` and the unreadable `package.json`. This combines the no-index install path (T-INST-64) with the unreadable-`package.json` warning path (T-INST-74) — both covered separately, but the combination tests that the `package.json` failure warning still fires for workflows without a default entry point. A buggy implementation could scope the `package.json` read/warn code to the same guard that triggers version comparison, and silently skip both on no-index workflows. **Conditional on `process.getuid() !== 0`.** *(Spec 10.6, 3.2, 10.4)*
+- **T-INST-73**: With `-y`, version mismatch is overridden and install proceeds. Version declaration preserved. **Pass `--no-install` per the section 4.10 auto-install-awareness rule** — this test's contract is the `-y`-version-mismatch-override behavior, not the post-commit auto-install pass. T-INST-120b separately covers the `-y` × auto-install interaction with `withFakeNpm`. *(Spec 10.6)*
+- **T-INST-72a**: Install-time version check for a no-index workflow with version mismatch. Single-workflow source containing `check.sh` (no `index` script) and a `package.json` declaring a loopx range not satisfied by the running version. `loopx install <source>` → exits with code 1 (version mismatch error). The version-mismatch error fires before the auto-install pass, so this test does not require `--no-install` (no commit, therefore no auto-install candidate); the rule's "pass `--no-install`" recommendation is for tests where the install would otherwise commit and auto-install would fire. This combines the no-index install path (T-INST-64) with version checking (T-INST-72) — both covered separately, but the combination tests that the version check still runs for workflows that lack a default entry point. *(Spec 10.6, 10.4)*
+- **T-INST-73a**: Same setup as T-INST-72a with `-y`. `loopx install -y <source>` → exits 0. Assert the workflow is installed with `check.sh` and `package.json` version declaration preserved. This is the `-y` override counterpart to T-INST-72a. **Pass `--no-install` per the section 4.10 auto-install-awareness rule** — the `-y` override commits the workflow and the workflow has a top-level `package.json`, so auto-install would fire by default; this test's contract is the version-mismatch-override behavior, not auto-install. *(Spec 10.6, 10.4)*
+- **T-INST-74**: Workflow `package.json` unreadable → warning, install proceeds (no version validation). **Source must be a tarball** (or another non-git source path), since Git does not reliably preserve mode 000 file permissions across clone. **Conditional on `process.getuid() !== 0`.** **Implementer note:** SPEC 10.6 / 3.2 require an unreadable workflow `package.json` to warn and install to proceed, while SPEC 10.7 / 10.9 treat a generic unreadable non-script file in staging as a staging failure (T-INST-79). The mode-000 `package.json` fixture therefore exercises a path where the implementation must explicitly exempt `package.json` from the generic unreadable-file staging-failure treatment — reading it is expected to fail (triggering the documented warning), but the file itself must still be copied/preserved during staging without the whole install aborting. An implementation that shares one unreadable-file code path for staging and version-checking will likely fail here. T-INST-74a/75a/76a and T-INST-60q/60r/60s inherit the same exemption requirement. This is a SPEC tension that the test suite exercises by design; no SPEC change is suggested. *(Spec 10.6, 3.2)*
+- **T-INST-74a**: Install-time `package.json` unreadable warning for a no-index workflow. Single-workflow source containing `check.sh` (no `index.*` script) and a `package.json` file with mode 000 (unreadable). **Source must be a tarball** (or another non-git source path). Run `loopx install <tarball-url>`. Assert: (a) exit code 0, (b) stderr contains exactly one unreadable-file warning for the workflow, (c) the workflow is installed at `.loopx/<name>/` and contains `check.sh`, and (d) a `package.json` entry exists at `.loopx/<name>/package.json` (the file's committed permission mode is **not** asserted — SPEC 10.6 / 3.2 / 10.7 require the warning to fire and the install to proceed but do not require loopx to preserve mode 000 / unreadability at the destination; an implementation that chmods the staged file to a readable mode before commit is conforming). The mode-000 fixture in the source is the test-harness mechanism for triggering the SPEC 3.2 unreadable-file warning path; the destination's permission bits are an implementation detail and are intentionally left unconstrained by this assertion. This combines the no-index install path (T-INST-64) with the unreadable-`package.json` warning path (T-INST-74) — both covered separately, but the combination tests that the `package.json` failure warning still fires for workflows without a default entry point. A buggy implementation could scope the `package.json` read/warn code to the same guard that triggers version comparison, and silently skip both on no-index workflows. **Conditional on `process.getuid() !== 0`.** *(Spec 10.6, 3.2, 10.4)*
 - **T-INST-75**: Workflow `package.json` invalid JSON → warning, install proceeds. *(Spec 10.6, 3.2)*
 - **T-INST-75a**: Install-time `package.json` invalid-JSON warning for a no-index workflow. Single-workflow source containing `check.sh` (no `index.*` script) and a `package.json` containing invalid JSON (e.g., `{broken`). Run `loopx install <source>`. Assert: (a) exit code 0, (b) stderr contains an invalid-JSON warning for the workflow, and (c) the workflow is installed at `.loopx/<name>/` and contains `check.sh` and the broken `package.json` (file is preserved as-is). This is the invalid-JSON counterpart to T-INST-74a (unreadable), combining the no-index install path (T-INST-64) with the invalid-JSON warning path (T-INST-75). *(Spec 10.6, 3.2, 10.4)*
 - **T-INST-76**: Workflow `package.json` invalid semver range → warning, install proceeds. *(Spec 10.6, 3.2)*
@@ -1506,24 +2969,35 @@ All install tests use local servers (HTTP, file:// git repos). No network access
 
 - **T-INST-77**: Multi-workflow install: all workflows pass preflight → all installed. *(Spec 10.7)*
 - **T-INST-78**: Multi-workflow install: one workflow fails preflight (e.g., name collision at destination) → entire install fails, no workflows written. Assert `.loopx/` unchanged. *(Spec 10.7)*
-- **T-INST-79**: Staging failure leaves `.loopx/` unchanged. Multi-workflow source (**must be a tarball** or another non-git source path — Git does not reliably preserve mode 000 file permissions across clone) where `ralph/` is valid (contains `index.sh`) and `broken/` contains a script file (`index.sh`) plus a non-script file with permissions set to `000` (unreadable). `loopx install <tarball-url>` → staging fails when trying to copy the unreadable file in `broken/`. Assert: exit code 1, `.loopx/` is unchanged (neither `ralph/` nor `broken/` was written), and the error message identifies the failing workflow and the underlying cause. **Conditional on `process.getuid() !== 0`.** *(Spec 10.7)*
-- **T-INST-80**: Multi-workflow install with `-y` succeeds despite destination collisions and version mismatches. Multi-workflow source where `ralph/` (with `index.sh`) has a destination collision (`.loopx/ralph/` already exists as a workflow with different content) and `other/` (with `index.sh` and a `package.json` declaring a loopx version range not satisfied by the running version) has a version mismatch. `loopx install -y <source>` → exits 0. Assert: `.loopx/ralph/` contains the new content from the source (replaced), and `.loopx/other/` is installed with its `package.json` version declaration preserved. *(Spec 10.7)*
+- **T-INST-79**: Staging failure leaves `.loopx/` unchanged. Multi-workflow source (git or tarball — the failure is driven by the seam, not by source shape) with two valid workflows `ralph/` (containing `index.sh`) and `broken/` (also containing `index.sh`). Set `NODE_ENV=test` and `LOOPX_TEST_INSTALL_FAULT=staging-fail:broken` (section 1.4) to deterministically inject an `EACCES` during staging of `broken/`. Run `loopx install <source>`. Assert: (a) exit code 1, (b) `.loopx/` is unchanged (neither `ralph/` nor `broken/` was written — the staging directory is cleaned up and the commit phase never runs, per SPEC 10.7), and (c) the error message identifies the failing workflow (`broken`) and the underlying cause (staging write failure / `EACCES`). The seam is used instead of a mode-000 file because SPEC 10.7 defines the failure *outcome* ("the staging directory is cleaned up and `.loopx/` is left unchanged") but does not require any specific source-shape trigger to cause staging to fail — an implementation that streams archive content into staging, chmods extracted files before copying, or otherwise avoids a literal copy of an unreadable file is conforming but would not fail staging on a mode-000 fixture. The seam decouples the SPEC-required outcome from an unspecified implementation detail. Runnable under any user (including `root`). *(Spec 10.7)*
+- **T-INST-80**: Multi-workflow install with `-y` succeeds despite destination collisions and version mismatches. Multi-workflow source where `ralph/` (with `index.sh`) has a destination collision (`.loopx/ralph/` already exists as a workflow with different content) and `other/` (with `index.sh` and a `package.json` declaring a loopx version range not satisfied by the running version) has a version mismatch. `loopx install -y <source>` → exits 0. Assert: `.loopx/ralph/` contains the new content from the source (replaced), and `.loopx/other/` is installed with its `package.json` version declaration preserved. **Pass `--no-install` per the section 4.10 auto-install-awareness rule** — `other/` has a top-level `package.json` and would trigger the post-commit auto-install pass; this test's contract is atomicity (`-y` overrides preflight failures and commits both workflows), not auto-install. *(Spec 10.7)*
 - **T-INST-80a**: Multi-workflow install with multiple preflight failures across different workflows (e.g., workflow A has a name collision at destination, workflow B has an invalid script name, workflow C declares a loopx version range not satisfied by the running version) → single aggregated error report listing all failures across all workflows, including the version mismatch. No workflows written. *(Spec 10.7)*
-- **T-INST-80b**: `-y` replacement preserves the existing workflow when staging fails. Multi-workflow source (**must be a tarball** or another non-git source path — Git does not reliably preserve mode 000 file permissions across clone) where `ralph/` is valid (has `index.sh`) and `other/` contains a script file (`index.sh`) plus a non-script file with permissions set to `000` (unreadable). `.loopx/ralph/` already exists as a workflow with known content. `loopx install -y <tarball-url>` → staging fails when trying to copy the unreadable file in `other/`. Assert: exit code 1, the existing `.loopx/ralph/` is still intact with its original content (not removed or modified — the commit phase never ran). **Conditional on `process.getuid() !== 0`.** *(Spec 10.7)*
+- **T-INST-80b**: `-y` replacement preserves the existing workflow when staging fails. Multi-workflow source (git or tarball — the failure is driven by the seam, not by source shape) with two valid workflows `ralph/` (containing `index.sh`) and `other/` (also containing `index.sh`). `.loopx/ralph/` already exists as a workflow with known content. Set `NODE_ENV=test` and `LOOPX_TEST_INSTALL_FAULT=staging-fail:other` (section 1.4) to deterministically inject an `EACCES` during staging of `other/`. Run `loopx install -y <source>`. Assert: (a) exit code 1, and (b) the existing `.loopx/ralph/` is still intact with its original content — not removed or modified, because under SPEC 10.7's stage-then-commit model, `-y` replacements are removed from `.loopx/` only during the commit phase, which never runs when staging fails. Uses the seam rather than a mode-000 source file for the same reason as T-INST-79: SPEC 10.7 defines the outcome, not a specific filesystem-permission trigger. Runnable under any user. *(Spec 10.7)*
 - **T-INST-80c**: Commit-phase failure reports which workflows were and were not committed. Multi-workflow source with three workflows: `alpha/`, `beta/`, `gamma/` (each with `index.sh`). Set `NODE_ENV=test` and `LOOPX_TEST_INSTALL_FAULT=commit-fail-after:1` in the process environment to simulate a rename failure after committing one workflow (see section 1.4, install fault injection seam — the seam is only honored when `NODE_ENV=test`). Assert: (a) exit code 1, (b) error output identifies which workflow(s) were successfully committed and which were not, and (c) exactly one workflow directory exists in `.loopx/`. *(Spec 10.7)*
-- **T-INST-80d**: Install-time `package.json` warning behavior is "once per affected workflow" and is not accidentally deduplicated by runtime-style first-entry logic. Install two workflows (**from a tarball source** or another non-git source path — Git does not reliably preserve mode 000 file permissions across clone), each with an unreadable `package.json` → each workflow's warning appears independently (two warnings, not one). **Conditional on `process.getuid() !== 0`.** *(Spec 3.2, 10.6)*
-- **T-INST-80e**: Install-time `package.json` warning behavior for invalid semver ranges is "once per affected workflow." Install two workflows, each with a valid `package.json` containing an invalid semver range for `loopx` (e.g., `"loopx": "not-a-range"`) → each workflow's warning appears independently (two warnings, not one). Install proceeds for both workflows (invalid semver skips version check, does not block install). This is the invalid-semver counterpart to T-INST-80d (unreadable files). *(Spec 3.2, 10.6)*
-- **T-INST-80f**: Install-time `package.json` warning behavior for invalid JSON is "once per affected workflow." Install two workflows, each with a `package.json` containing invalid JSON (e.g., `{broken`) → each workflow's warning appears independently (two warnings, not one). Install proceeds for both workflows (invalid JSON skips version check, does not block install). This is the invalid-JSON counterpart to T-INST-80d (unreadable files) and T-INST-80e (invalid semver). *(Spec 3.2, 10.6)*
+- **T-INST-80c2**: Commit-phase failure skips the post-commit auto-install pass — `npm install` does **not** run even on workflows committed before the failure. SPEC 10.10 specifies "After the commit phase (section 10.7) completes, unless `--no-install` is present, loopx performs a post-commit auto-install pass over the committed workflows" — the natural reading of "the commit phase completes" is "the commit phase completes successfully" (a partial / failed commit phase has not completed). Under that interpretation, a commit-phase failure gates the auto-install pass entirely: no committed-before-failure workflow receives an auto-install pass. T-INST-80c covers the commit-failure reporting behavior; this test pins down the auto-install gating behavior on the same failure. Multi-workflow source with three workflows: `alpha/`, `beta/`, `gamma/` — each has `index.sh` **and a top-level `package.json`** (so each would trigger auto-install if the pass ran). Use `withFakeNpm({ exitCode: 0, logFile })` to capture any `npm install` invocation, and set `NODE_ENV=test` / `LOOPX_TEST_INSTALL_FAULT=commit-fail-after:1` to fail the commit phase after the first workflow commits. Run `loopx install <source>`. Assert: (a) exit code 1 (the commit failure is the terminal error), (b) exactly one workflow directory exists in `.loopx/` (matching T-INST-80c's commit-failure outcome), (c) **the fake-npm shim log is empty** — zero `npm install` invocations occurred, even though the committed workflow has a `package.json` that would normally trigger auto-install, and (d) no `.gitignore` was synthesized in the committed workflow's directory (`.gitignore` safeguard runs under the same trigger as `npm install` per SPEC 10.10, so when auto-install is gated, the safeguard is also gated). A buggy implementation that ran auto-install on the committed workflow after a commit failure would produce at least one shim invocation, failing (c). An implementation that ran the safeguard but skipped `npm install` would produce a `.gitignore` and fail (d). This test pins down SPEC 10.10's "commit phase completes successfully" preamble — pairing this test with T-INST-80c under a single commit-failure fixture cleanly distinguishes "which workflows committed" (reporting) from "which workflows received auto-install" (gating). *(Spec 10.10, 10.7)*
+- **T-INST-80d**: Install-time `package.json` warning behavior is "once per affected workflow" and is not accidentally deduplicated by runtime-style first-entry logic. Install two workflows (**from a tarball source** or another non-git source path — Git does not reliably preserve mode 000 file permissions across clone), each with an unreadable `package.json` → each workflow's warning appears independently (two warnings, not one). **Pass `--no-install` per the section 4.10 auto-install-awareness rule** — both workflows have a top-level `package.json` and would otherwise trigger the post-commit auto-install pass; this test's contract is install-time `package.json` warning cardinality, not auto-install. **Conditional on `process.getuid() !== 0`.** *(Spec 3.2, 10.6)*
+- **T-INST-80e**: Install-time `package.json` warning behavior for invalid semver ranges is "once per affected workflow." Install two workflows, each with a valid `package.json` containing an invalid semver range for `loopx` (e.g., `"loopx": "not-a-range"`) → each workflow's warning appears independently (two warnings, not one). Install proceeds for both workflows (invalid semver skips version check, does not block install). **Pass `--no-install` per the section 4.10 auto-install-awareness rule** — both workflows have a top-level `package.json` and would otherwise trigger the post-commit auto-install pass; this test's contract is warning cardinality, not auto-install. This is the invalid-semver counterpart to T-INST-80d (unreadable files). *(Spec 3.2, 10.6)*
+- **T-INST-80f**: Install-time `package.json` warning behavior for invalid JSON is "once per affected workflow." Install two workflows, each with a `package.json` containing invalid JSON (e.g., `{broken`) → each workflow's warning appears independently (two warnings, not one). Install proceeds for both workflows (invalid JSON skips version check, does not block install). **Pass `--no-install` per the section 4.10 auto-install-awareness rule** — both workflows have a top-level `package.json` (albeit malformed) and would otherwise be considered for the post-commit auto-install pass; this test's contract is warning cardinality, not auto-install behavior. (Note: SPEC 10.10 separately says malformed `package.json` skips auto-install; this test's `--no-install` is defensive and decouples warning cardinality from any auto-install evaluation that would otherwise occur.) This is the invalid-JSON counterpart to T-INST-80d (unreadable files) and T-INST-80e (invalid semver). *(Spec 3.2, 10.6)*
 - **T-INST-80g**: `-y` does not override a zero-workflow source. `loopx install -y <source>` where the source contains no root-level script files and no subdirectories that qualify as workflows → error, exit code 1, regardless of `-y`. *(Spec 10.3, 10.7)*
 - **T-INST-80h**: `-y` does not override invalid workflow or script names. `loopx install -y <source>` where the source contains a workflow with an invalid script name (e.g., `-bad.sh`) → error, exit code 1, regardless of `-y`. *(Spec 10.4, 10.7)*
 - **T-INST-80i**: `-y` does not override same-base-name collisions within a workflow. `loopx install -y <source>` where the source contains a workflow with `check.sh` and `check.ts` (same base name, different extensions) → error, exit code 1, regardless of `-y`. *(Spec 10.4, 10.7)*
 - **T-INST-80j**: `-y` does not override an invalid workflow name. `loopx install -y <source>` where the derived workflow name violates `[a-zA-Z0-9_][a-zA-Z0-9_-]*` (e.g., source directory named `bad.name`) → error, exit code 1, regardless of `-y`. *(Spec 10.4, 10.7)*
 
+##### Staging-directory Cleanup Visibility (Known Gap)
+
+SPEC 10.7 / 10.9 require the temporary staging directory itself to be removed on
+staging / pre-commit failure. Current tests assert the externally visible contract
+(`.loopx/` remains unchanged) but do not directly observe the implementation-private
+staging directory, whose location and naming are unspecified.
+
+- **T-INST-79a (not yet directly covered)**: Temporary staging directory is removed after a staging-phase failure. Deterministic coverage would require a test-only seam that exposes the staging-directory path.
+
 #### Tarball Install
 
 - **T-INST-81**: Multi-workflow tarball install with exact name derivation. Create a `.tar.gz` whose source root (after any wrapper-directory stripping) contains subdirectories `ralph/` (with `index.sh`) and `other/` (with `index.sh`). Install the tarball. Assert installed paths are exactly `.loopx/ralph/` and `.loopx/other/`, with the expected scripts present. Workflow names are derived from the source-root subdirectory names. *(Spec 10.2)*
 - **T-INST-82**: Wrapper-directory stripping for multi-workflow tarball. Create a `.tar.gz` with a single top-level directory `pkg/` containing `pkg/ralph/index.sh` and `pkg/other/index.sh`. After extraction, `pkg/` is stripped and the source root becomes the contents of `pkg/`. Assert installed paths are `.loopx/ralph/` and `.loopx/other/` (not `.loopx/pkg/`). *(Spec 10.2)*
 - **T-INST-83**: No wrapper-directory stripping for multi-entry tarball. Create a `.tar.gz` with multiple top-level entries `ralph/index.sh` and `other/index.sh` (no single wrapper directory). After extraction, the entries are used directly as the source root. Assert installed paths are `.loopx/ralph/` and `.loopx/other/`. *(Spec 10.2)*
+- **T-INST-83b**: No wrapper-directory stripping when extraction yields a single directory plus a sibling root-level file. SPEC 10.2 says "If extraction yields a **single top-level directory**, that directory's contents become the source root (wrapper-directory stripping). If extraction yields **multiple top-level entries**, the extracted contents are used directly as the source root." A tarball whose top-level entries are exactly one directory and one or more sibling files (e.g., a wrapper directory plus a sibling `README.md` at the archive root) yields multiple top-level entries — the SPEC's "single top-level directory" condition is not satisfied, so wrapper stripping must **not** occur. T-INST-82 covers the single-directory-only branch (stripping fires); T-INST-83 covers the multi-directory branch (no stripping); the **single-directory-plus-sibling-file** edge case lies between these two and is uncovered. A buggy implementation that normalized "ignore root-level files when deciding wrapper-stripping" or that stripped on "any single top-level **directory** entry" without also requiring "no other top-level entries" would wrongly fire wrapper-stripping on this fixture, producing a different installed-path layout. Create a `.tar.gz` named `archive.tar.gz` whose root contains exactly two top-level entries: `pkg/` (a directory containing `pkg/index.sh`) and `README.md` (a sibling file at the archive root). After extraction, the source root has multiple top-level entries (`pkg/` and `README.md`), so no wrapper stripping fires; the source root has no root-level files **with supported script extensions** (`README.md` is not a supported script extension), but `pkg/` qualifies as a workflow (contains a top-level script with a supported extension), so the source classifies as **multi-workflow** per SPEC 10.3. Run `loopx install <tarball-url>`. Assert: (a) exit code 0, (b) `.loopx/pkg/` is committed and contains `index.sh` (the workflow name is the **subdirectory** name `pkg`, not the **archive** name `archive` — multi-workflow tarballs derive workflow names from source-root subdirectory names per SPEC 10.2), (c) **`.loopx/archive/` does not exist** — wrapper stripping did not occur, so the archive name is not the workflow name, and (d) `.loopx/README.md` does not exist — the source-root `README.md` is a non-workflow support file and is not copied (per SPEC 10.3 multi-workflow self-containment, T-INST-83a). Together with T-INST-82 (single-directory wrapper stripping) and T-INST-83 (multi-directory no-wrapper-stripping), this closes the third extraction shape (single-dir + sibling-file). *(Spec 10.2, 10.3)*
 - **T-INST-83a**: Multi-workflow tarball self-containment. Create a `.tar.gz` whose source root (after any wrapper-directory stripping) contains two workflow subdirectories `ralph/` (with `index.sh`) and `other/` (with `index.sh`), plus root-level support files `README.md` and `LICENSE`, a root-level support directory `docs/` (containing `docs/guide.md`), and a non-workflow directory `shared/` (containing only `shared/config.json` — no top-level script files). `loopx install <tarball-url>` → exit code 0. Assert: (a) `.loopx/ralph/` and `.loopx/other/` are installed and contain their respective scripts, (b) `.loopx/README.md`, `.loopx/LICENSE`, `.loopx/docs/`, and `.loopx/shared/` do NOT exist — no root support files or directories are copied. Per SPEC 10.2, classification after extraction is source-type-agnostic, so the multi-workflow self-containment rules that apply to git sources (T-INST-54 covers root support files, T-INST-54c covers root support directories, T-INST-55 covers non-workflow subdirectories skipped) must apply equally to tarball sources. Existing tarball coverage (T-INST-81–83) pins down wrapper stripping and workflow-name derivation but does not assert self-containment; this test closes that gap. *(Spec 10.2, 10.3)*
 - **T-INST-84**: `.tgz` extension handled identically. *(Spec 10.2)*
 - **T-INST-85**: Single-workflow tarball: workflow name derived from archive name (URL last segment minus `.tar.gz`/`.tgz`, query/fragment stripped). *(Spec 10.2)*
@@ -1534,26 +3008,181 @@ All install tests use local servers (HTTP, file:// git repos). No network access
 
 #### Git Install
 
-- **T-INST-87**: Shallow clone (`--depth 1`). Verify clone has only 1 commit. *(Spec 10.2)*
+- **T-INST-87**: Shallow clone (`--depth 1`). Use `withFakeGit({ logFile })` so every `git` invocation loopx makes is recorded to a log file (the shim wraps the real `git` and is transparent to loopx's cloning). Run `loopx install <git-source>` against a local bare repo. Assert the log contains a `git clone` invocation (the only-one-clone cardinality is incidental and not separately asserted) whose argv includes a depth-1 specification — accept either the two-token form `--depth 1` (separate argv entries `["--depth", "1"]`) or the equals form `--depth=1` (single argv entry). Per SPEC 10.2 "The repository is cloned with `--depth 1` (shallow clone) into a temporary location." **The argv ordering of the depth flag relative to the source URL or destination path is not asserted** — SPEC 10.2 specifies only that shallow-clone is performed, not a specific argv layout, and standard `git clone` accepts options in any position before the URL/destination operands. The test's assertion is satisfied by any conforming `git clone <... --depth 1 ...> <url> [<dst>]` or `git clone <url> [<dst>] <... --depth=1 ...>` argv arrangement that preserves a valid `git clone` invocation. The `--depth 1` flag on the recorded `git clone` invocation is the black-box-visible surface for the SPEC 10.2 shallow-clone contract; SPEC 10 does not normatively define whether installed workflows retain `.git/` metadata, so this test does not assert anything about post-install `.git/` presence or absence. *(Spec 10.2)*
 - **T-INST-88**: Single-workflow git repo: name derived from repo URL minus `.git`. *(Spec 10.2)*
 - **T-INST-89**: Multi-workflow git repo: workflow names derived from subdirectory names. *(Spec 10.2)*
 
 #### Common Rules
 
 - **T-INST-90**: `.loopx/` directory created if it doesn't exist. *(Spec 10)*
-- **T-INST-91**: loopx does not run `npm install` / `bun install` after clone/extract. *(Spec 10.9)*
 - **T-INST-92**: HTTP 404 during tarball download → error, exit code 1, no partial directory. *(Spec 10.9)*
+- **T-INST-92a**: HTTP 500 (server error) during tarball download → error, exit code 1, no partial directory. T-INST-92 covers the 4xx (client-error) branch, which is the most common failure mode. This test covers the 5xx (server-error) branch — both are HTTP error responses but a buggy implementation could special-case 4xx error handling (e.g., treating 404 as "not found" but treating 5xx as a transient retry-able condition that ends up succeeding spuriously, or surfacing differently). Use the tarball-download fault-injection mock server (the same harness mechanism used by T-INST-92, parameterized for status code) to return HTTP 500 for the tarball URL. Run `loopx install <url-returning-500>`. Assert: (a) exit code 1, (b) stderr surfaces the download failure (HTTP 500 reference is not pinned — the exact error wording is implementation-defined, since loopx may translate the HTTP status into a generic download-failure message), and (c) no partial workflow directory is left under `.loopx/` — if `.loopx/` pre-existed with unrelated workflows, those remain unmodified; otherwise `.loopx/` was not created. **Do not assert directly on the implementation-private staging directory**: the staging-path location and naming are unspecified (see known gap T-INST-79a — section 4.10 "Staging-directory Cleanup Visibility"), so a black-box test must limit itself to the externally visible SPEC 10.9 contract ("`.loopx/` itself unchanged, no destination partials"). Pinning down the implementation-private staging-path cleanup is the business of T-INST-79a, not this test. This test pins down that loopx treats both 4xx and 5xx as fatal install failures with the same externally-observable cleanup behavior — the SPEC 10.9 download-failure path does not branch on HTTP status class. *(Spec 10.9)*
+- **T-INST-92b**: HTTP 3xx (redirect) during tarball download is treated as a non-2xx install failure; `Location:` is not auto-followed. SPEC 10.9 says "Install failure cleanup (pre-commit failure modes): Any pre-commit install failure (download error, **HTTP non-2xx**, git clone failure, extraction failure, post-download validation failure) ... exits with code 1." T-INST-92 / T-INST-92a cover 4xx and 5xx; this test covers the 3xx branch. A buggy implementation might transparently follow `Location:` redirects (treating 3xx as a successful download path) and complete the install. Use `startLocalHTTPServer` to register two routes: a primary route at `/redirect.tar.gz` that responds with HTTP 302 and a `Location: http://localhost:PORT/real.tar.gz` header, and a secondary route at `/real.tar.gz` that serves an otherwise-valid `.tar.gz` (single-workflow source with `index.sh`). The harness records every incoming request to both routes. Run `loopx install http://localhost:PORT/redirect.tar.gz`. Assert: (a) exit code 1 (the 302 is a non-2xx response and therefore an install failure under SPEC 10.9), (b) stderr surfaces a download failure (exact wording implementation-defined; the test does not pin a specific phrase, only that the failure category is download-failure / non-2xx, not extraction-failure), (c) no workflow was committed — `.loopx/` is unchanged (matches the externally visible SPEC 10.9 contract), and (d) **the secondary `/real.tar.gz` route received zero hits** — verifying via the harness's request log that loopx did not transparently follow the redirect to a tarball that would have succeeded. Assertion (d) is the key signal that distinguishes "loopx treated 302 as a failure" from "loopx silently followed the redirect and the install ended up failing for some unrelated reason"; the secondary route serves a working tarball precisely so that any redirect-following implementation would succeed (exit 0) on this fixture, making the exit-code-1 assertion unambiguous. T-INST-92 (404) and T-INST-92a (500) cover the 4xx / 5xx branches; this closes the 3xx branch. *(Spec 10.9)*
+- **T-INST-92c**: Tarball download transport error (connection reset before headers) is treated as a download failure. SPEC 10.9 enumerates **"download error"** as the first pre-commit failure mode, distinct from "HTTP non-2xx" — the two categories are listed separately, so a transport-level failure (TCP reset, abrupt socket close before headers, TLS handshake failure, DNS resolution failure) is a SPEC-named install-failure mode and not collapsed into the HTTP-status branch. T-INST-92 / T-INST-92a / T-INST-92b cover the HTTP-non-2xx branch (404, 500, 302); T-INST-94 / T-INST-95 cover the extraction-failure branch (corrupt archive, empty archive); T-INST-93 covers the git-clone-failure branch. The transport-error branch is not currently covered. A buggy implementation that raised an uncaught exception on a socket reset (rather than translating it into a clean SPEC 10.9 download-failure with exit 1 and `.loopx/` unchanged) would pass all the existing T-INST-92* / T-INST-94 / T-INST-95 tests but fail this case. Use `startLocalHTTPServer` to register a route at `/reset.tar.gz` whose handler **accepts the connection, then immediately destroys the underlying socket without writing any response headers or body** (e.g., `(req, res) => { req.socket.destroy(); }` for a Node `http.Server` — the socket is closed mid-request, before any HTTP response line is sent). Run `loopx install http://localhost:PORT/reset.tar.gz`. Assert: (a) exit code 1 (the transport error is a SPEC 10.9 download failure), (b) stderr surfaces a download / network failure (exact wording implementation-defined; the test does not pin a specific phrase, only that the failure category is download / network failure — **not** an HTTP-status failure and **not** an extraction failure), (c) `.loopx/` is unchanged (matches the externally visible SPEC 10.9 cleanup contract — pre-commit failures leave `.loopx/` itself unchanged; if `.loopx/` pre-existed with unrelated workflows, those remain unmodified; otherwise `.loopx/` was not created), and (d) no partial workflow directory or staging artifact under `.loopx/` is left behind. **Do not assert directly on the implementation-private staging directory** for the same reason as T-INST-92 / T-INST-92a (per known gap T-INST-79a — section 4.10 "Staging-directory Cleanup Visibility"). Together with T-INST-92 / T-INST-92a / T-INST-92b (HTTP non-2xx branch) and T-INST-94 / T-INST-95 (extraction branch), this closes coverage of the SPEC 10.9 pre-commit failure-mode enumeration on the tarball-source path: download-error (this test), HTTP non-2xx (404 / 500 / 302), extraction failure (corrupt / empty archive). The git-clone-failure branch (T-INST-93) and post-download validation-failure branch (covered by the install-time validation tests T-INST-61 / T-INST-78 / etc.) round out the rest of the SPEC 10.9 list. *(Spec 10.9, 12)*
 - **T-INST-93**: Git clone failure (non-existent repo) → error, exit code 1, no partial directory. *(Spec 10.9)*
 - **T-INST-94**: Tarball extraction failure (corrupt archive) → error, exit code 1, no partial directory. *(Spec 10.9)*
 - **T-INST-95**: Empty tarball (valid `.tar.gz` with no entries) → error, exit code 1. *(Spec 10.9)*
 - **T-INST-96**: Successful single-workflow git install → installed workflow is runnable via `loopx run <name>`. *(Spec 10)*
-- **T-INST-97a**: Single-workflow install failure cleanup. Simulate a single-workflow install that fails after the target directory `.loopx/<name>/` has been partially created (e.g., by serving a tarball that extracts successfully but fails post-download validation). Assert: (a) exit code 1, (b) the partially created `.loopx/<name>/` directory is removed, and (c) `.loopx/` is left clean (no partial workflow directory remains). *(Spec 10.9)*
+- **T-INST-97a**: Pre-commit failure leaves `.loopx/` unchanged. Per Spec 10.7 / 10.9's stage-then-commit model, any pre-commit install failure (source download, extraction, preflight, staging — enumerated in Spec 10.9's "Install failure cleanup" bullet) leaves `.loopx/` itself unchanged; no destination-path cleanup is required. Create a single-workflow source (git or tarball — the failure is driven by the seam, not by source shape). Before running install, snapshot the state of `.loopx/` (either empty or containing unrelated workflows). Set `NODE_ENV=test` and `LOOPX_TEST_INSTALL_FAULT=staging-fail:<name>` (section 1.4, where `<name>` is the derived workflow name) to deterministically inject an `EACCES` during staging. Run `loopx install <source>`. Assert: (a) exit code 1, (b) `.loopx/` is byte-identical to the pre-install snapshot (no new workflow directory under `.loopx/<name>/`, and any pre-existing sibling workflows unmodified), and (c) stderr identifies the failing workflow and the underlying cause. This rewrites the earlier cleanup-of-partial-workflow-directory assertion to match SPEC 10.9 post-ADR-0004: under stage-then-commit, the staging directory is the only thing that could be partial, and it is removed; `.loopx/` itself never receives a partial write. Uses the staging-fail seam for the same reason as T-INST-79: SPEC 10.9 defines the outcome, not a specific filesystem-permission trigger. Runnable under any user. *(Spec 10.7, 10.9)*
+- **T-INST-97a2**: Pre-commit failure (preflight) leaves `.loopx/` unchanged. Create a single-workflow source whose workflow name violates name restrictions. Snapshot `.loopx/`, run install, assert exit 1 and `.loopx/` unchanged. This is the preflight-fails-at-single-workflow variant of T-INST-97a (which covers the staging failure); together they pin down that neither pre-commit phase leaves `.loopx/` in a partial state for single-workflow sources. *(Spec 10.7, 10.9)*
 - **T-INST-97b**: Successful install does not create `.loopx/package.json`. Run a successful single-workflow git install into a project. Assert: (a) exit code 0, (b) the workflow is installed at `.loopx/<name>/`, and (c) `.loopx/package.json` does not exist. There is no `.loopx/`-level manifest — version authority lives only in the project root `package.json` and each workflow's own `package.json`. *(Spec 10.6)*
 
+#### Auto-install of Workflow Dependencies (Spec 10.10)
+
+All tests in this block use `withFakeNpm` (section 2.3) to control `npm`'s behavior deterministically. The helper records every invocation to a log file so tests can assert which workflows `npm install` was invoked for, in what order, and with what environment. Without the fake shim, these tests would be flaky (depend on real npm + registry) or impossible (`spawnFailure`, signal, non-zero exit cannot be driven by real npm reliably).
+
+##### Auto-install Trigger
+
+- **T-INST-110**: Default post-commit `npm install` runs once per committed workflow with top-level `package.json`, sequentially. Install a multi-workflow source where `alpha/` has a top-level `package.json` (and `alpha/index.sh`) and `beta/` has a top-level `package.json` (and `beta/index.sh`). Use `withFakeNpm({ exitCode: 0, sleepSeconds: 1, logFile })`. The per-invocation `sleepSeconds: 1` is what makes the non-overlap assertion in (e) testable: with immediate-exit shims, two concurrent invocations could both record start/end timestamps within a single millisecond, and a non-overlap assertion against millisecond-resolution timestamps could pass vacuously even on a buggy implementation that ran the two `npm install` children in parallel. A 1-second per-invocation window means a parallel implementation would produce visibly overlapping intervals (the second invocation's start would precede the first invocation's end by ~1 second), and the non-overlap assertion catches that — pinning down the **sequential / non-overlapping** half of SPEC 10.10's "sequentially in an implementation-defined order; npm children do not overlap" requirement. Run `loopx install <source>` (no `--no-install`). Assert: (a) exit code 0, (b) the shim log records exactly two invocations, (c) **the set** of invocation cwds is exactly `{ .loopx/alpha/, .loopx/beta/ }` — each workflow was invoked exactly once, in either order (the test does **not** assume or assert a specific alpha-vs-beta order, because SPEC 10.10 explicitly makes the cross-workflow auto-install order implementation-defined and not an external conformance contract), (d) each invocation's argv is **exactly** `["install"]` — no additional flags (`--production`, `--ignore-scripts`, `--omit=dev`, etc.) are passed, per SPEC 10.10 "does not pass `--production` / `--omit=dev` / `--ignore-scripts` / any other flags", (e) the two invocations do not overlap in wall-clock time (the log records start/end timestamps for each shim execution; assert the second invocation's start is after the first invocation's end, regardless of which workflow is which — under the 1-second per-invocation sleep, a parallel implementation would fail this assertion deterministically), and (f) **no aggregate failure report is emitted on stderr** — SPEC 10.10's "If no auto-install failures occurred, no aggregate report is emitted" clause; the success-path negative assertion pins down that the aggregate-report machinery does not engage when both workflows succeed (an implementation that emitted an empty / "0 failures" aggregate report on a clean two-workflow auto-install pass would fail this assertion). **Coverage scope for "sequentially in an implementation-defined order".** This test pins down the full set of externally observable guarantees SPEC 10.10 makes about auto-install ordering: that each workflow is invoked exactly once and that the two `npm install` children do not overlap in wall-clock time. It does **not** assert any specific cross-workflow ordering between `alpha` and `beta`, because SPEC 10.10 explicitly states that "the cross-workflow order of the post-commit auto-install pass is not an external conformance contract; implementations may use their internal commit order or any other implementation-defined order." Together with T-INST-110b, T-INST-110a, and T-INST-114, this test establishes that auto-install processes each committed workflow exactly once and sequentially, which is the entire externally testable contract under the current SPEC wording. *(Spec 10.10)*
+- **T-INST-110a**: `npm install` is skipped silently for workflows without a top-level `package.json`. Multi-workflow source where `alpha/` has `alpha/index.sh` + `alpha/package.json`, and `beta/` has only `beta/index.sh` (no `package.json`). Use `withFakeNpm`. Run install. Assert: (a) exit code 0, (b) the shim log records exactly one invocation — for `alpha/`, (c) no warning about `beta/` missing a `package.json` — the skip is silent (Spec 10.10 "Workflows without a top-level `package.json` are skipped silently"). *(Spec 10.10)*
+- **T-INST-110c**: Presence of `package.json` alone triggers auto-install — dependency content is not inspected. Single-workflow source with `index.sh` and a minimal `package.json` containing exactly `{ "name": "minimal-workflow", "version": "1.0.0" }` (no `dependencies`, no `devDependencies`, no `scripts`, no `loopx` field). Use `withFakeNpm({ exitCode: 0, logFile })`. Run `loopx install <source>`. Assert: (a) exit code 0, (b) the fake-npm shim log records exactly one invocation for the workflow (argv `["install"]`, cwd = `.loopx/<name>/`), (c) a synthesized `.gitignore` was created in the workflow directory, and (d) **no aggregate failure report is emitted on stderr** — SPEC 10.10's "If no auto-install failures occurred, no aggregate report is emitted" clause; the success-path negative assertion pins down that the aggregate-report machinery does not engage on a clean auto-install pass. Per SPEC 10.10 "The trigger is the presence of a top-level `package.json`; whether that file declares any dependencies is not inspected." A buggy implementation that skipped auto-install when the `package.json` lists zero dependencies would fail (b) / (c); an implementation that emitted an empty / "0 failures" aggregate report on a clean auto-install pass would fail (d). *(Spec 10.10, 2.1)*
+- **T-INST-110b**: `-w <name>` scopes auto-install to the selected workflow. Same source as T-INST-110 (both `alpha/` and `beta/` have `package.json`). Run `loopx install -w alpha <source>`. Assert shim log records exactly one invocation, for `alpha/`, and none for `beta/`. Extends T-INST-57 (selective installation) to the auto-install pass. *(Spec 10.10, 10.8)*
+- **T-INST-110d**: Auto-install fires on a no-`index` workflow. SPEC 2.1 allows workflows without an `index` script (they can still be targeted explicitly via `workflow:script`), and SPEC 10.10 triggers auto-install solely on the presence of a top-level `package.json` — it does not require an `index` entry. Single-workflow source with `check.sh` (non-`index` script) and a top-level `package.json` (e.g., `{ "name": "my-workflow", "version": "1.0.0" }`) and no `index.*` file. Use `withFakeNpm({ exitCode: 0, logFile })`. Run `loopx install <source>`. Assert: (a) exit code 0, (b) the fake-npm shim log records **exactly one** invocation for the workflow (cwd = `.loopx/<name>/`, argv = `["install"]`), (c) a synthesized `.gitignore` exists at `.loopx/<name>/.gitignore` containing `node_modules`, and (d) the installed workflow still does not have an `index` script (loopx did not invent one). Per SPEC 10.10 the trigger is top-level `package.json` alone; a buggy implementation that gated auto-install on the presence of an `index` entry (either by fiat or because it only walked discovered-script workflows) would fail this test. *(Spec 10.10, 2.1, 10.4)*
+- **T-INST-110e**: Nested `package.json` alone does **not** trigger auto-install. SPEC 10.10's trigger is a `package.json` at the workflow's **top level** (`.loopx/<workflow-name>/package.json`); `package.json` files in subdirectories are not triggers. Single-workflow source with `index.sh` plus `lib/package.json` (i.e., a nested-only `package.json`) and no top-level `package.json`. Use `withFakeNpm({ exitCode: 0, logFile })`. Run `loopx install <source>`. Assert: (a) exit code 0, (b) the fake-npm shim log records **zero** invocations (the trigger did not fire because the top-level `package.json` is absent), (c) no `.gitignore` is synthesized at `.loopx/<name>/.gitignore` (the safeguard runs under the same trigger conditions as `npm install`), and (d) the nested `lib/package.json` is preserved under `.loopx/<name>/lib/package.json` byte-for-byte. This pins down the "top-level" part of the trigger rule — an implementation that recursively scanned each installed workflow for any `package.json` and fired auto-install per-hit would fail this test. *(Spec 10.10, 2.1)*
+- **T-INST-110f**: Auto-install fires on a **selected no-`index` workflow under `-w`**. Combines T-INST-110b (`-w` scopes auto-install to the selected workflow) with T-INST-110d (no-`index` workflow still triggers auto-install when a top-level `package.json` is present). The two interactions are covered separately — `-w` × auto-install for index-bearing workflows (T-INST-110b), and no-index × auto-install for full-source installs (T-INST-110d) — but the no-index × `-w` × auto-install combination is uncovered. A buggy implementation could gate the SPEC 10.10 auto-install pass on either "workflow has an `index` entry" or "workflow was selected via the full-source path, not via `-w`" and pass both T-INST-110b and T-INST-110d while failing this combination. Multi-workflow source where `tools/` contains `tools/check.sh` (a non-`index` script) and `tools/package.json` with content `{ "name": "tools", "version": "1.0.0" }` (no `index.*`), and `other/` contains `other/index.sh` + `other/package.json` (a sibling workflow that would normally also trigger auto-install — its presence here proves the `-w` scoping is working). Use `withFakeNpm({ exitCode: 0, logFile })`. Run `loopx install -w tools <source>` (no `--no-install`). Assert: (a) exit code 0, (b) the fake-npm shim log records **exactly one** invocation (cwd = `.loopx/tools/`, argv = `["install"]`) — the selected no-index workflow triggered auto-install despite having no `index` entry, and the unselected `other/` workflow was not invoked because of `-w`, (c) a synthesized `.gitignore` exists at `.loopx/tools/.gitignore` containing `node_modules`, (d) `.loopx/tools/check.sh` is present and `.loopx/tools/index.*` does not exist (loopx did not invent an index entry), and (e) `.loopx/other/` does not exist (selective install only writes the selected workflow). T-INST-64c proves that no-index workflows install correctly under `-w`; this test pins down that the post-commit auto-install pass also runs for them, completing the no-index × `-w` × SPEC 10.10 interaction. *(Spec 10.10, 10.8, 2.1)*
+- **T-INST-110g**: Auto-install fires on a **tarball source** with a top-level `package.json` — pinning down that SPEC 10.10's post-commit auto-install pass is source-type-agnostic. SPEC 10.10 says the trigger applies "after `loopx install` commits workflow files" and is keyed solely on the presence of a top-level `package.json` — it does not condition the trigger on source type. The existing T-INST-110 / T-INST-110a / T-INST-110c / T-INST-110d / T-INST-110f positive-trigger tests are source-type-agnostic in their wording but the implementation may default to git fixtures, leaving the tarball-source path uncovered for the positive auto-install trigger surface. T-INST-113a covers the malformed-`package.json` (mode 000) failure mode on a tarball source (where a tarball is required because git does not preserve mode 000), but that is a *negative* path. A buggy implementation that wired auto-install only into the post-commit phase of the git-source code path — e.g., by calling `runAutoInstall()` inside the git-clone branch but forgetting to call it in the tarball-extraction branch — would pass T-INST-110 et al. (under git defaults) and T-INST-113a (where the tarball path correctly skips auto-install due to malformed `package.json`) while silently violating SPEC 10.10 on every successful tarball install. **Setup — naming discipline.** Per SPEC 10.2, the workflow name for a single-workflow tarball source is the **archive-name** (the URL's last path segment with archive extensions removed and query strings / fragments stripped) — **not** the wrapper directory name inside the tarball, which is stripped during the SPEC 10.2 wrapper-stripping step before classification. To eliminate any ambiguity in the assertions below, the test **intentionally makes the archive name and the wrapper directory name identical** (both `tarball-workflow`), so the unambiguous workflow name `tarball-workflow` reaches `.loopx/<name>/` whether the reader interprets `<name>` as "the wrapper directory" or "the archive-derived workflow name" — they are the same string here. **Setup — fixture.** Single-workflow tarball source served via `startLocalHTTPServer` (per the section 2.3 install-test conventions): a `.tar.gz` archive **named `tarball-workflow.tar.gz`** whose root contains a single wrapper directory **`tarball-workflow/`** with `tarball-workflow/index.sh` (a minimal valid script — e.g., emits `{"stop":true}`) and `tarball-workflow/package.json` (e.g., `{ "name": "tarball-workflow", "version": "1.0.0" }`). After SPEC 10.2 wrapper-stripping, the source root is the contents of `tarball-workflow/`; the source is classified as single-workflow (root has script files); and per SPEC 10.2 "For single-workflow tarball sources, the workflow name is the **archive-name**" the workflow name is `tarball-workflow` (derived from `tarball-workflow.tar.gz`). The source has **no** pre-existing `.gitignore`, so the `.gitignore` safeguard must synthesize one. Use `withFakeNpm({ exitCode: 0, logFile })` to make the `npm install` invocation deterministic and observable. Run `loopx install http://localhost:PORT/tarball-workflow.tar.gz` (no `--no-install`, no `-w`). **Assert.** (a) exit code 0, (b) the workflow is committed at `.loopx/tarball-workflow/` (the archive-derived workflow name) with `index.sh` and `package.json` from the source byte-for-byte (file-level commit succeeded on the tarball path), (c) the fake-npm shim log records **exactly one** invocation with cwd = `.loopx/tarball-workflow/` and argv = `["install"]` — auto-install ran post-commit on the tarball path (no `--production`, no `--ignore-scripts`, etc., per SPEC 10.10's "does not pass ... any other flags" rule), and (d) a synthesized `.gitignore` exists at `.loopx/tarball-workflow/.gitignore` containing the single line `node_modules` (optionally with a trailing newline) — the safeguard ran on the tarball path. Together with T-INST-110 (multi-workflow source whose source type is not pinned in the test wording — typically a git fixture in current implementations) and T-INST-113a (tarball + mode-000 `package.json` → auto-install correctly skipped), this closes the "auto-install trigger fires regardless of source type" surface for the positive path. *(Spec 10.10, 10.2, 10.1)*
+
+##### `--no-install` Opt-Out
+
+- **T-INST-111**: `--no-install` suppresses both `npm install` and `.gitignore` synthesis. Single-workflow source with top-level `package.json` but no `.gitignore`. Use `withFakeNpm` to observe any invocation. Run `loopx install --no-install <source>`. Assert: (a) exit code 0, (b) the shim log is empty (no `npm` invocations), (c) `.loopx/<name>/.gitignore` was **not** created, (d) other install-time behavior succeeded (workflow files present at `.loopx/<name>/`). Per Spec 10.10 "`--no-install` ... does not suppress any other install-time behavior; only the `npm install` step and the `.gitignore` safeguard ... are skipped." *(Spec 10.10)*
+- **T-INST-111a**: `--no-install` on a workflow with a pre-existing `.gitignore` leaves that file unchanged. Source's `.gitignore` contains `dist/\n`. Use `withFakeNpm`. Run `loopx install --no-install <source>`. Assert: (a) no `npm` invocation, (b) the installed `.loopx/<name>/.gitignore` has the same content as the source (`dist/\n`) — loopx did not touch it. *(Spec 10.10)*
+- **T-INST-111b**: `--no-install` does **not** suppress preflight validation. Single-workflow source with a top-level `package.json` declaring a loopx version range not satisfied by the running version. Use `withFakeNpm({ exitCode: 0, logFile })`. Run `loopx install --no-install <source>`. Assert: (a) exit code 1 with a version-mismatch error, (b) the shim log is empty (auto-install never ran), (c) no `.gitignore` was synthesized, and (d) the workflow was not committed. This proves `--no-install` suppresses only the post-commit auto-install pass, not source download / preflight validation / commit behavior. *(Spec 10.10, 10.6)*
+- **T-INST-111c**: `--no-install` does **not** suppress nonfatal `package.json` parse / validation warnings. T-INST-111b covers the **fatal** preflight branch (version mismatch — exit 1, workflow not committed). This test pins down the **nonfatal** branch: a malformed `package.json` produces a SPEC 3.2 / 10.6 warning at install time but does not block the commit, and `--no-install` must not gate that warning either. Single-workflow source with `index.sh` and a top-level `package.json` containing **invalid JSON** (e.g., `{broken`). Use `withFakeNpm({ exitCode: 0, logFile })`. Run `loopx install --no-install <source>`. Assert: (a) exit code 0 — invalid JSON is non-fatal (T-INST-113 establishes this without `--no-install`); `--no-install` suppresses only auto-install / safeguard, not commit, (b) the shim log is empty (no `npm` invocation — `--no-install` suppresses auto-install regardless of the package warning), (c) stderr contains exactly one `package.json` parse-failure warning for the workflow (the SPEC 3.2 install-time warning fires regardless of `--no-install`; `--no-install` does not gate install-time package validation warnings), (d) `.loopx/<name>/.gitignore` was **not** created (safeguard skipped under `--no-install`), and (e) the workflow is committed at `.loopx/<name>/` with `index.sh` and the malformed `package.json` byte-for-byte. T-INST-113 covers the same warning + auto-install-skip without `--no-install`; T-INST-111 covers `--no-install` without a malformed `package.json`. This test covers the intersection: `--no-install` suppresses only the auto-install + safeguard behaviors specified in SPEC 10.10, not install-time package-validation warnings or file-level commit. An implementation that wrongly suppressed all `package.json`-related warnings under `--no-install` (treating `--no-install` as a "skip everything package-related" knob) would fail (c). *(Spec 10.10, 3.2)*
+
+##### `.gitignore` Safeguard
+
+- **T-INST-112**: Missing `.gitignore` is created with exactly one line: `node_modules`, **and the safeguard runs before `npm install` is spawned**. SPEC 10.10 specifies: "Immediately before spawning `npm install` in a workflow directory, loopx checks for a top-level `.gitignore` ... If none exists, loopx creates one containing the single line `node_modules`." A post-install end-state assertion alone ("`.gitignore` exists after install") cannot distinguish "safeguard ran before npm spawn" from "loopx ran npm first and created `.gitignore` afterward" — a buggy implementation could populate `node_modules/` first and then synthesize `.gitignore` retroactively, producing the same final filesystem state but violating the SPEC ordering. To pin the ordering down, the fake-npm shim must record the **state at shim process start**: extend `withFakeNpm` to record, for each invocation, whether `<cwd>/.gitignore` existed when the shim was first invoked (e.g., capture `fs.existsSync('.gitignore')` and the file's content as the very first action in the shim's preamble, before any other side effect). The recorded state is then asserted by the test. Single-workflow source with `package.json` but no `.gitignore`. Use `withFakeNpm({ exitCode: 0, recordGitignoreAtStart: true, logFile })`. Run `loopx install <source>`. Assert: (a) exit 0, (b) `.loopx/<name>/.gitignore` exists at the end, (c) its end-state content is exactly `node_modules` (optionally with a single trailing newline — implementation-defined), (d) the fake-npm shim log records exactly one invocation for the workflow with cwd = `.loopx/<name>/`, and (e) **the shim-start `.gitignore`-existed marker is `true`** for the recorded invocation, with the recorded content being exactly `node_modules` (matching (c)) — the safeguard had already created `.gitignore` before `npm install` was spawned, per SPEC 10.10's "Immediately before spawning `npm install`" wording. A buggy implementation that ran npm first and synthesized `.gitignore` afterward would produce a `false` shim-start marker (or a missing-content marker) and fail (e). **Implementer note for the harness.** This test requires `withFakeNpm` to expose a `recordGitignoreAtStart` option that adds a per-invocation `gitignoreAtStart: { existed: boolean, content?: string }` field to each `FakeNpmInvocation` log entry; the recording happens as the first side effect inside the shim's Bash preamble (before any of the shim's configured `stdout`/`stderr`/`createFiles` actions), guaranteeing it observes filesystem state at the moment of spawn. *(Spec 10.10)*
+- **T-INST-112a**: Existing **regular** `.gitignore` is left unchanged (no append, no rewrite, no warning). Source's `.gitignore` is a regular file containing `dist/\n# my custom comment\n` — installed under SPEC 10.11's symlink-materialization rules as a regular file at `.loopx/<name>/.gitignore`. Use `withFakeNpm({ exitCode: 0 })`. Run install. Assert: (a) exit 0, (b) `.loopx/<name>/.gitignore` content is byte-identical to the source's (`dist/\n# my custom comment\n`) — no `node_modules` line appended, (c) no warning on stderr about `node_modules` not being listed, (d) `npm install` still ran (the `lstat`-regular dispatch took the "regular file → leave unchanged → proceed" branch per SPEC 10.10). The non-regular branches (directory, symlink, FIFO, socket) are exercised by T-INST-112e and the symlink-known-gap entry below. *(Spec 10.10)*
+- **T-INST-112a2**: Source `.gitignore` that is a **symlink to a regular file** is materialized as a regular file by SPEC 10.11 staging / copy and then satisfies SPEC 10.10's regular-file branch — auto-install proceeds normally and the materialized content is preserved unchanged. SPEC 10.11 says "During the staging / copy phase, loopx does **not** preserve symlink entries as symlinks in installed workflows. Any symlink that is part of a selected workflow is resolved and materialized into the destination as a regular copied file or directory" — with the explicit example "Symlinked non-script files or directories inside a selected workflow's copied content are likewise materialized as real files or directories." A workflow `.gitignore` is a non-script file inside the workflow, so the materialization rule applies; the resulting installed entry is a regular file and SPEC 10.10's `lstat` dispatch must take the regular-file branch. T-INST-112a covers the same regular-file branch when the **source** `.gitignore` was already a regular file; this test extends that coverage to the source-symlink case to pin down the **interaction** between SPEC 10.11 (source-symlink materialization) and SPEC 10.10 (`.gitignore` safeguard `lstat` dispatch). T-INST-112g (and its sub-cases) covers the post-commit symlink case via the `gitignore-replace-with-symlink:` seam — that test exists precisely because SPEC 10.11 materializes source symlinks before commit and ordinary install inputs cannot produce a committed symlink `.gitignore`. This test is the positive companion: it proves the materialization actually happens for `.gitignore` (rather than the safeguard accidentally observing the un-materialized symlink and failing). A buggy implementation that materialized source symlinks for script files but missed `.gitignore` (e.g., because the materialization pass walked only entries matching the discovered-script-extension set) would commit a symlink at `.loopx/<name>/.gitignore`, the safeguard would observe that symlink, and auto-install would surface a `.gitignore` safeguard failure for an ordinary source — a regression the safeguard tests alone cannot catch. **Setup.** Single-workflow source containing `index.sh` (minimal script — e.g., emits `{"stop":true}`), a top-level `package.json` (e.g., `{ "name": "symlink-gitignore-workflow", "version": "1.0.0" }`), a target file `gitignore-template` containing `dist/\n# project-custom\n`, and a `.gitignore -> gitignore-template` symlink at the workflow root. **Parameterize over both source types** (per the SPEC 10.2 / 10.11 source-form parity used elsewhere in this block — git and tarball must both materialize source symlinks): for the git source, commit the symlink directly into the local bare repo so a real `git clone` materializes it through the SPEC 10.11 path; for the tarball source, build a `.tar.gz` archive that records the entry as a symlink (e.g., `tar --create --file pkg.tar.gz <wf>/`) so SPEC 10.11 materialization runs through the tarball-extraction branch. Use `withFakeNpm({ exitCode: 0, logFile })`. Run `loopx install <source>` (no `--no-install`). **Assert** (per source-type variant). (a) exit code 0 — the materialization succeeded and the safeguard took the regular-file branch with no failure. (b) `.loopx/<name>/.gitignore` is a **regular file** — verified via `lstat` returning a `S_IFREG` entry type and **not** `S_IFLNK`. A buggy implementation that copied the source symlink as-is would surface `S_IFLNK` and fail this assertion. (c) `.loopx/<name>/.gitignore` content is byte-identical to the symlink **target's** content (`dist/\n# project-custom\n`) — SPEC 10.11 materialization resolves the symlink and copies the target's bytes; loopx neither appends `node_modules` nor mutates the materialized content (per SPEC 10.10's regular-file branch "loopx leaves it unchanged and proceeds"). (d) the fake-npm shim log records exactly one invocation with cwd = `.loopx/<name>/` and argv = `["install"]` — auto-install ran, proving the safeguard saw a regular file (not a symlink) and dispatched correctly. (e) **no aggregate failure report** is emitted on stderr — the safeguard succeeded for the materialized regular `.gitignore`, so SPEC 10.10's failure-reporting machinery does not engage. (f) `.loopx/<name>/gitignore-template` is also present as a regular file containing `dist/\n# project-custom\n` (the materialization preserves the original target as well, since the target is itself a non-script workflow file selected by the workflow's contents — pinning down that SPEC 10.11 materializes the symlink to a regular file at the link's name *without* deleting or hiding the target file's separate copy). Together with T-INST-112a (regular-file source) and T-INST-112g sub-cases (symlink-via-seam post-commit failure), this completes the SPEC 10.10 × SPEC 10.11 coverage matrix at the `.gitignore` safeguard surface: source-regular-file → safeguard-regular branch (T-INST-112a), source-symlink → materialized-regular-file → safeguard-regular branch (this test), and post-commit symlink-via-seam → safeguard-symlink-failure branch (T-INST-112g). *(Spec 10.10, 10.11)*
+- **T-INST-112b**: `.gitignore` synthesis is skipped when the workflow has no top-level `package.json`. Source has `index.sh` but no `package.json`. Run install. Assert `.loopx/<name>/.gitignore` was not created. `.gitignore` synthesis runs only under the same trigger as `npm install`. *(Spec 10.10)*
+- **T-INST-112c**: `.gitignore` write failure skips `npm install` for that workflow, contributes to aggregate failure, and **does not abort the auto-install pass over the remaining workflows**. Multi-workflow source with **three** workflows: `alpha/`, `beta/`, and `gamma/` — each has a normal `package.json` and no pre-existing `.gitignore` (so loopx must synthesize one for each). Use `withFakeNpm({ exitCode: 0, logFile })`. Run install with `NODE_ENV=test` and `LOOPX_TEST_AUTOINSTALL_FAULT=gitignore-write-fail:beta,gamma` (the fault-injection seam from section 1.4 — **both** `beta/` and `gamma/` are gated to fail). Assert: (a) exit code 1 (aggregate failure due to both `beta/` and `gamma/`'s safeguard write failures), (b) **the set** of shim-log invocation cwds is exactly `{ .loopx/alpha/ }` — `npm install` ran only for `alpha/` (its safeguard succeeded) and was skipped on both `beta/` and `gamma/` (their safeguards failed). The two-failing-workflow form is what makes continuation-after-failure observable regardless of the implementation-defined auto-install order: SPEC 10.10 explicitly leaves cross-workflow order implementation-defined, so `beta/` and `gamma/` may be in any positions in the sequence — but regardless of ordering, an implementation that aborted the pass at the **first** failure would invoke `npm install` for `alpha/` only when `alpha/` is processed **before** both `beta/` and `gamma/`. Since with two failing workflows there is no auto-install order in which `alpha/` runs **after** the first failure without the pass having continued past at least one failure, asserting that `alpha/` ran and both `beta/` and `gamma/` are listed in the aggregate report proves the pass continued past the first failure in every possible auto-install order. (c) stderr contains an aggregate failure report listing **both** `beta/` and `gamma/` with `.gitignore` write failures — a pass that aborted at the first failure would list at most one of them. (d) `alpha/` is **not** listed in the aggregate report (its safeguard and `npm install` both succeeded). **No sequential-overlap assertion on shim invocations is made here** — only `alpha/` reaches the shim under this fault configuration, so a non-overlap assertion across multiple `FakeNpmInvocation` timestamps would be vacuous. The "sequentially in an implementation-defined order; npm children do not overlap" axis of SPEC 10.10 is exercised separately by T-INST-110 (two workflows, both reach the shim) and T-INST-114 (three workflows, all reach the shim) where multiple npm invocations actually occur. Using the `LOOPX_TEST_AUTOINSTALL_FAULT` seam (rather than real filesystem permissions) keeps the test deterministic, CI-friendly, and runnable under any user (including `root`). *(Spec 10.10)*
+- **T-INST-112d**: `.gitignore` write failure does **not** roll back committed workflow files. SPEC 10.10 explicitly says "Committed workflow files are not rolled back" when a `.gitignore` write fails — the failure is recorded on the same aggregate-report footing as an `npm install` spawn failure, and the user remediates manually. T-INST-112c covers the aggregate-report and continuation-after-failure clauses but does not explicitly assert the no-rollback contract on the failing workflow's directory. Same multi-workflow fixture as T-INST-112c (`alpha/`, `beta/`, `gamma/` each with `index.sh` + `package.json` and no pre-existing `.gitignore`), same fault: `LOOPX_TEST_AUTOINSTALL_FAULT=gitignore-write-fail:beta,gamma`. After `loopx install <source>` exits 1, assert: (a) `.loopx/alpha/index.sh`, `.loopx/alpha/package.json`, and `.loopx/alpha/.gitignore` (synthesized) all exist on disk with their intended contents — `alpha/` had a successful safeguard + `npm install`, (b) `.loopx/beta/index.sh` and `.loopx/beta/package.json` exist on disk byte-for-byte from the source — file-level commit succeeded for `beta/` even though its safeguard write failed; loopx did not delete or move `beta/`'s committed files, (c) `.loopx/beta/.gitignore` does **not** exist (the safeguard write failed, so no `.gitignore` was committed for `beta/`), and (d) `.loopx/gamma/` mirrors `beta/`'s state (same shape, same no-`.gitignore` outcome — proves no-rollback applies independently to each failing workflow rather than rolling back all failures together). **Do not assert directly on the implementation-private staging-directory path**: the staging-path location and naming are unspecified (see known gap T-INST-79a — section 4.10 "Staging-directory Cleanup Visibility"), so a black-box test must limit itself to externally visible state (committed workflow files remaining in `.loopx/`). A previous revision of this test additionally asserted "no temporary staging-directory leftovers remain at the install-staging-root path"; that assertion is removed here because it contradicts the known gap and is unreachable without an implementation-specific staging-path seam. T-INST-117 covers the analogous no-rollback contract for `npm install` non-zero-exit failures; this test extends that contract to the `.gitignore`-write-failure branch, which is normatively part of the same rule but exercises a different code path. *(Spec 10.10)*
+- **T-INST-112e**: Pre-existing `.gitignore` **directory** at `.loopx/<workflow>/.gitignore` is a safeguard failure (the non-regular branch from SPEC 10.10's `lstat` dispatch). Multi-workflow source where `alpha/` contains `alpha/index.sh`, `alpha/package.json`, and `alpha/.gitignore/` — a directory entry named `.gitignore` containing at least one placeholder file (e.g., `alpha/.gitignore/README` with arbitrary content) so the directory is non-empty and is preserved through git/tarball install — and `beta/` is a normal workflow with `beta/index.sh` + `beta/package.json` and **no** pre-existing `.gitignore`. The fixture is parameterized across git and tarball sources (per the SPEC 10.2 / 10.11 source-form parity used elsewhere in this block), since both transports must preserve a directory named `.gitignore` at the workflow root through file-level install. Use `withFakeNpm({ exitCode: 0, sleepSeconds: 1, logFile })`. Run `loopx install <source>`. Assert: (a) exit code 1 — `alpha/`'s safeguard failure contributes to final exit `1` per SPEC 10.10's "the failure contributes to final exit code `1`" clause. (b) The fake-npm shim log records exactly one invocation with cwd `.loopx/beta/` — `npm install` ran for `beta/` (its safeguard succeeded via the ENOENT-creation branch — loopx synthesized a regular `.gitignore` containing `node_modules`) and was skipped for `alpha/` (the directory at `.loopx/alpha/.gitignore` failed the `lstat`-regular check). (c) The aggregate failure report on stderr lists `alpha/` as a `.gitignore` safeguard failure and does **not** list `beta/`. (d) `.loopx/alpha/index.sh` and `.loopx/alpha/package.json` exist on disk byte-for-byte from the source — no rollback of committed workflow files per SPEC 10.10's "Committed workflow files are not rolled back" clause. (e) `.loopx/alpha/.gitignore` still exists as a **directory** with its placeholder file unchanged — loopx did **not** delete the directory, replace it with a regular file, mutate its contents, or otherwise touch the entry; "the entry is left unchanged" per the SPEC 10.10 non-regular branch. (f) `.loopx/beta/.gitignore` exists as a **regular file** containing exactly `node_modules` (optionally with a single trailing newline — implementation-defined, mirroring T-INST-112's content assertion), and `.loopx/beta/index.sh` + `.loopx/beta/package.json` exist on disk. The two-workflow form (one with directory `.gitignore`, one with no pre-existing `.gitignore`) proves both halves of the dispatch in a single test: the non-regular branch fails for `alpha/`, the ENOENT-creation branch succeeds for `beta/`, and the test catches a buggy implementation that aborted the entire pass on the first safeguard failure (which would also skip `beta/`, failing (b) and (f)) as well as one that wrongly proceeded with `npm install` against a directory `.gitignore` for `alpha/` (which would invoke the shim with cwd `.loopx/alpha/`, failing (b)) or one that mutated `alpha/.gitignore/` in any way (failing (e)). T-INST-112c covers continuation past `.gitignore` write failures via the `LOOPX_TEST_AUTOINSTALL_FAULT=gitignore-write-fail:` seam; this test covers the externally observable directory-`.gitignore` failure path through real filesystem entries (no seam needed), pinning down the "directory" instance of SPEC 10.10's "directory, symlink, FIFO, socket, or other non-regular entry" enumeration on its concrete-fixture surface. The symlink instance is exercised separately by T-INST-112g (using the `LOOPX_TEST_AUTOINSTALL_FAULT=gitignore-replace-with-symlink:` seam) across three symlink-shape sub-cases (regular-file target, broken, cyclic), because SPEC 10.11 materializes source symlinks before commit and ordinary install inputs cannot produce a committed symlink `.gitignore`. *(Spec 10.10, 10.11)*
+- **T-INST-112f**: `--no-install` suppresses the `.gitignore` safeguard entirely, even when the existing entry is non-regular. SPEC 10.10's safeguard bullet says "The safeguard is skipped entirely under `--no-install`" — the `lstat` dispatch is short-circuited before it runs, so a non-regular pre-existing `.gitignore` (which would otherwise produce a safeguard failure per T-INST-112e) does **not** trigger any failure under `--no-install`. Same fixture as T-INST-112e — multi-workflow source where `alpha/` contains `alpha/index.sh`, `alpha/package.json`, and `alpha/.gitignore/` (a non-empty directory), and `beta/` contains `beta/index.sh` + `beta/package.json` with no pre-existing `.gitignore`. Use `withFakeNpm({ logFile })` (any exit configuration; the shim must not be invoked under `--no-install` per SPEC 10.10). Run `loopx install --no-install <source>`. Assert: (a) exit code 0 — the non-regular `.gitignore` directory does **not** trigger a safeguard failure under `--no-install` because the safeguard never ran. (b) The fake-npm shim log records **zero** invocations (no `npm install` for either workflow per SPEC 10.10's `--no-install` semantics). (c) `.loopx/alpha/.gitignore` still exists as a directory with its placeholder file unchanged — loopx did not touch the entry. (d) `.loopx/beta/.gitignore` does **not** exist — the safeguard did not synthesize one for `beta/` either, per SPEC 10.10 "The safeguard is skipped entirely under `--no-install`". (e) Both workflow directories are committed at `.loopx/alpha/` and `.loopx/beta/` with their source files (file-level commit succeeded for both; only auto-install was suppressed per SPEC 10.10 `--no-install`). (f) **No aggregate failure report** on stderr — no auto-install failures occurred because the safeguard was skipped entirely, not failed. This test pins down that `--no-install` is checked **before** the `lstat` dispatch — an implementation that ran the `lstat` check first and only suppressed the npm spawn under `--no-install` would emit a safeguard-failure aggregate-report entry for `alpha/` and fail (a), (c), and (f). Together with T-INST-111 (`--no-install` with no pre-existing `.gitignore`) and T-INST-111a (`--no-install` with a regular pre-existing `.gitignore`), this completes the `--no-install` × `.gitignore`-state coverage matrix across all three concrete states observable through ordinary install inputs: {no entry, regular file, non-regular entry}. *(Spec 10.10)*
+- **T-INST-112g**: Pre-existing `.gitignore` **symlink** at `.loopx/<workflow>/.gitignore` is a safeguard failure across all three symlink-shape sub-cases per SPEC 10.10's "A symlink named `.gitignore` does not satisfy the safeguard, even if it resolves to a regular file. Broken and cyclic symlinks are treated as symlink entries and therefore fail the safeguard" rule. SPEC 10.11 materializes source symlinks as regular files / directories during install staging / copy, so a committed symlink at `.loopx/<workflow>/.gitignore` cannot be produced through ordinary install inputs — deterministic coverage uses the `LOOPX_TEST_AUTOINSTALL_FAULT=gitignore-replace-with-symlink:<workflow>[=<kind>]` seam from section 1.4, which replaces (or creates) the path with a symlink immediately after commit and before the per-workflow safeguard `lstat`, so the dispatch observes a symlink entry. Parameterize the test over the three `<kind>` values, each in its own multi-workflow run with a normal sibling `beta/` workflow (no pre-existing `.gitignore`) to prove the safeguard pass continues past the symlink failure rather than aborting:
+
+  - **T-INST-112g-1 (`regular-file-target`)**: Multi-workflow source where `alpha/` has `alpha/index.sh` + `alpha/package.json` (and **no** pre-existing `.gitignore` in source, so SPEC 10.11 materialization is irrelevant), and `beta/` has `beta/index.sh` + `beta/package.json`. Use `withFakeNpm({ exitCode: 0, sleepSeconds: 1, logFile })` and set `LOOPX_TEST_AUTOINSTALL_FAULT=gitignore-replace-with-symlink:alpha=regular-file-target`. The seam, after commit and before the per-workflow safeguard `lstat` for `alpha/`, creates `.loopx/alpha/.gitignore-target` as a regular file containing `node_modules` and creates `.loopx/alpha/.gitignore` as a symlink pointing to `.gitignore-target`. Run `loopx install <source>`. Assert: (a) exit code 1 — the symlink is a safeguard failure even though its target is a regular file containing the protective content. (b) The fake-npm shim log records exactly one invocation with cwd `.loopx/beta/` — `npm install` ran for `beta/` (its safeguard succeeded via the ENOENT-creation branch) and was skipped for `alpha/` (the symlink failed the `lstat`-regular check). (c) The aggregate failure report on stderr lists `alpha/` as a `.gitignore` safeguard failure; `beta/` is not listed. (d) `.loopx/alpha/index.sh` and `.loopx/alpha/package.json` exist on disk byte-for-byte (no rollback). (e) `.loopx/alpha/.gitignore` is still a symlink (using `lstat` to inspect the entry type, not `stat`) pointing to `.gitignore-target`, and `.loopx/alpha/.gitignore-target` still exists as a regular file containing `node_modules` — loopx did **not** delete the symlink, replace it, or follow it to overwrite the target. (f) `.loopx/beta/.gitignore` is a regular file containing `node_modules`. This sub-case is the load-bearing one: it pins the SPEC-text invariant "even if it resolves to a regular file" — an implementation that used `stat` (follows symlinks) instead of `lstat` for the safeguard check would observe a regular file at the symlink's target, take the regular-file branch, and proceed with `npm install` for `alpha/`, failing (a) and (b).
+  - **T-INST-112g-2 (`broken`)**: Same fixture and shim configuration as T-INST-112g-1, with `LOOPX_TEST_AUTOINSTALL_FAULT=gitignore-replace-with-symlink:alpha=broken`. The seam creates `.loopx/alpha/.gitignore` as a symlink pointing to a non-existent target (e.g., `./does-not-exist`) without creating that target. Run `loopx install <source>`. Assert (a)–(f) as in T-INST-112g-1, with (e) modified: `.loopx/alpha/.gitignore` is still a symlink whose `readlink` target is `./does-not-exist`, and `.loopx/alpha/does-not-exist` does **not** exist. This sub-case pins the SPEC clause "Broken ... symlinks are treated as symlink entries and therefore fail the safeguard" — an implementation that fell back to `stat` after `lstat` revealed a symlink would receive `ENOENT` from the `stat` call and could mis-route to the ENOENT-creation branch (creating a regular `.gitignore` and clobbering the broken symlink). The test catches this by asserting the symlink entry is preserved and that no `npm install` ran for `alpha/`.
+  - **T-INST-112g-3 (`cycle`)**: Same fixture and shim configuration as T-INST-112g-1, with `LOOPX_TEST_AUTOINSTALL_FAULT=gitignore-replace-with-symlink:alpha=cycle`. The seam creates two symlinks at `.loopx/alpha/.gitignore -> .gitignore-loop` and `.loopx/alpha/.gitignore-loop -> .gitignore`. Run `loopx install <source>`. Assert (a)–(f) as in T-INST-112g-1, with (e) modified: both `.loopx/alpha/.gitignore` and `.loopx/alpha/.gitignore-loop` remain as symlinks (verified via `lstat`), each pointing at the other. This sub-case pins the SPEC clause "cyclic symlinks are treated as symlink entries and therefore fail the safeguard" — an implementation that resolved the symlink (e.g., via `realpath` or `fs.statSync`) would encounter `ELOOP` and could produce a different failure category (e.g., a generic `lstat` failure) than the symlink branch; this test asserts the safeguard-failure category is reported uniformly across the three sub-cases.
+
+  Together with T-INST-112e (directory), T-INST-112i (FIFO), T-INST-112j (socket), and T-INST-112c (write-failure via the `gitignore-write-fail:` seam) plus T-INST-112h (top-level `.gitignore` `lstat`-failure-other-than-`ENOENT` via the `gitignore-lstat-fail:` seam), this completes coverage of SPEC 10.10's non-regular enumeration ("directory, symlink, FIFO, socket, or other non-regular entry") and the safeguard-failure clause's `lstat`-failure branch. *(Spec 10.10, 10.11)*
+
+- **T-INST-112h**: Top-level `.gitignore` `lstat` failure other than `ENOENT` is a safeguard failure — `npm install` is skipped for that workflow, the failure is recorded in the aggregate report, exit code is 1, committed workflow files are not rolled back, and auto-install continues to later workflows. SPEC 10.10's safeguard-failure clause enumerates the non-`ENOENT` `lstat` failure as one of two write-related branches: "`lstat` failure other than `ENOENT`, or a write failure when synthesizing `.gitignore`: loopx treats this as a `.gitignore` safeguard failure under the same aggregate-report / skip-`npm install` semantics." T-INST-112c covers the **write-failure** branch via the `gitignore-write-fail:` seam; this test covers the **`lstat`-failure** branch via the `gitignore-lstat-fail:` seam from section 1.4. The branches are observably distinct: the `lstat` failure short-circuits the dispatch before any write attempt is made, so a buggy implementation that handled write failures correctly but conflated `lstat`-failure with `ENOENT` (and proceeded to synthesize `.gitignore`) would pass T-INST-112c while violating SPEC 10.10's "`lstat` failure other than `ENOENT`" clause. Multi-workflow source with **three** workflows: `alpha/`, `beta/`, and `gamma/`, each with `index.sh` + a top-level `package.json` and **no** pre-existing `.gitignore` (so the safeguard runs in the synthesis path for the workflows whose `lstat` succeeds). Use `withFakeNpm({ exitCode: 0, logFile })`. Run install with `NODE_ENV=test` and `LOOPX_TEST_AUTOINSTALL_FAULT=gitignore-lstat-fail:beta,gamma` (the seam — **both** `beta/` and `gamma/` are gated to fail at `lstat`). Assert: (a) exit code 1 (aggregate failure due to both `beta/` and `gamma/`'s safeguard `lstat` failures), (b) **the set** of shim-log invocation cwds is exactly `{ .loopx/alpha/ }` — `npm install` ran only for `alpha/` (its safeguard succeeded via the `ENOENT`-creation branch) and was skipped on both `beta/` and `gamma/` (their safeguards short-circuited at the `lstat` failure before any write or spawn). The two-failing-workflow form follows the same continuation-after-failure rationale as T-INST-112c: with two failures, no implementation-defined auto-install order can mask a buggy implementation that aborted the pass at the first failure. (c) stderr contains an aggregate failure report listing **both** `beta/` and `gamma/` as `.gitignore` safeguard failures — a pass that aborted at the first failure would list at most one of them. (d) `alpha/` is **not** listed in the aggregate report (its safeguard and `npm install` both succeeded). (e) committed workflow files are **not** rolled back: `.loopx/alpha/index.sh`, `.loopx/alpha/package.json`, `.loopx/beta/index.sh`, `.loopx/beta/package.json`, `.loopx/gamma/index.sh`, and `.loopx/gamma/package.json` all exist on disk byte-for-byte from the source per SPEC 10.10's "Committed workflow files are not rolled back" clause. (f) `.loopx/alpha/.gitignore` exists as a regular file containing exactly `node_modules` (synthesis succeeded for `alpha/`, mirroring T-INST-112's content assertion); `.loopx/beta/.gitignore` and `.loopx/gamma/.gitignore` do **not** exist on disk (the safeguard short-circuited at `lstat` before the write attempt — distinguishes the `lstat`-failure branch from the write-failure branch, where a write attempt may have produced a partial file). Using the `LOOPX_TEST_AUTOINSTALL_FAULT=gitignore-lstat-fail:` seam (rather than real filesystem permissions) keeps the test deterministic, CI-friendly, and runnable under any user (including `root`). *(Spec 10.10)*
+
+- **T-INST-112i**: Pre-existing `.gitignore` **FIFO** at `.loopx/<workflow>/.gitignore` is a safeguard failure (the FIFO instance of SPEC 10.10's "directory, symlink, FIFO, socket, or other non-regular entry" enumeration). Multi-workflow source where `alpha/` contains `alpha/index.sh` + `alpha/package.json` (and **no** pre-existing `.gitignore` in source, so SPEC 10.11 materialization is irrelevant), and `beta/` is a normal workflow with `beta/index.sh` + `beta/package.json` and **no** pre-existing `.gitignore` either. Ordinary install inputs cannot place a FIFO at the workflow's `.gitignore` path because git transports do not preserve FIFOs and tarball transports cannot carry FIFO entries through standard archive formats — deterministic coverage uses the `LOOPX_TEST_AUTOINSTALL_FAULT=gitignore-replace-with-fifo:<workflow>` seam from section 1.4, which creates a FIFO at `.loopx/<workflow>/.gitignore` immediately after commit and before the per-workflow safeguard `lstat`, so the dispatch observes a FIFO entry. Use `withFakeNpm({ exitCode: 0, sleepSeconds: 1, logFile })` and set `LOOPX_TEST_AUTOINSTALL_FAULT=gitignore-replace-with-fifo:alpha`. Run `loopx install <source>`. Assert: (a) exit code 1 — the FIFO is a safeguard failure per SPEC 10.10's non-regular-entry enumeration; the failure contributes to final exit code `1` per SPEC 10.10's "the failure contributes to final exit code `1`" clause. (b) The fake-npm shim log records exactly one invocation with cwd `.loopx/beta/` — `npm install` ran for `beta/` (its safeguard succeeded via the `ENOENT`-creation branch) and was skipped for `alpha/` (the FIFO failed the `lstat`-regular check); proves the safeguard pass continues past the FIFO failure rather than aborting. (c) The aggregate failure report on stderr lists `alpha/` as a `.gitignore` safeguard failure and does **not** list `beta/`. (d) `.loopx/alpha/index.sh` and `.loopx/alpha/package.json` exist on disk byte-for-byte (no rollback). (e) `.loopx/alpha/.gitignore` is **still a FIFO** (verified via `lstat` returning a `S_IFIFO` entry type) — loopx did **not** delete the FIFO, replace it with a regular file, or otherwise touch the entry; "the entry is left unchanged" per SPEC 10.10's non-regular branch. (f) `.loopx/beta/.gitignore` is a regular file containing `node_modules` (the safeguard succeeded for `beta/` via the `ENOENT`-creation branch, mirroring T-INST-112's content assertion). The two-workflow form (one with FIFO `.gitignore`, one with no pre-existing `.gitignore`) proves both halves of the dispatch in a single test, mirroring T-INST-112e's directory pattern and T-INST-112g's symlink pattern. This sub-case pins the FIFO branch of SPEC 10.10's non-regular enumeration — an implementation that special-cased the regular/symlink/directory entry types but fell through to a generic "unrecognized" path for FIFO (e.g., proceeding with `npm install` against a FIFO `.gitignore`, or replacing the FIFO with a synthesized regular file) would fail (a), (b), or (e). *(Spec 10.10)*
+
+- **T-INST-112j**: Pre-existing `.gitignore` **socket** at `.loopx/<workflow>/.gitignore` is a safeguard failure (the socket instance of SPEC 10.10's "directory, symlink, FIFO, socket, or other non-regular entry" enumeration). Companion to T-INST-112i (FIFO). Same fixture and shim configuration as T-INST-112i — multi-workflow source where `alpha/` has `alpha/index.sh` + `alpha/package.json` and `beta/` has `beta/index.sh` + `beta/package.json`, neither with a pre-existing `.gitignore` — and use `LOOPX_TEST_AUTOINSTALL_FAULT=gitignore-replace-with-socket:alpha`. The seam creates a Unix-domain socket at `.loopx/alpha/.gitignore` immediately after commit and before the per-workflow safeguard `lstat`, so the dispatch observes a socket entry. Run `loopx install <source>`. Assert (a)–(f) as in T-INST-112i, with (e) modified: `.loopx/alpha/.gitignore` is **still a socket** (verified via `lstat` returning a `S_IFSOCK` entry type). This sub-case pins the socket branch of SPEC 10.10's non-regular enumeration — an implementation that handled FIFO entries correctly but fell through to a generic path for sockets (or one that conflated FIFOs and sockets without distinguishing) would still pass T-INST-112i while failing this test. *(Spec 10.10)*
+
+- **T-INST-112k**: Pre-existing **regular but unreadable** `.gitignore` at `.loopx/<workflow>/.gitignore` (mode `000`) — safeguard treats it as a regular file, proceeds to `npm install`, emits no safeguard failure, and leaves the file unchanged (including its mode bits). SPEC 10.10's regular-file branch normatively says: "loopx leaves it unchanged and proceeds. loopx does not read, parse, validate, append to, or **inspect the file's contents or permissions**; the workflow author is responsible for any pre-existing regular `.gitignore`." T-INST-112a covers the **content** axis of "leaves unchanged" (byte-identical content after install) but not the **permission-non-inspection** axis: a buggy implementation that read the file's content (or attempted to append to it, then bailed on `EACCES`) would still pass T-INST-112a's content assertion against a normally-readable fixture, since the read would succeed and produce no observable mutation. This test pins down the SPEC clause that loopx must **not** attempt to read or otherwise inspect a regular `.gitignore`'s permissions. Single-workflow source where the workflow has `index.sh`, a top-level `package.json`, and a regular `.gitignore` containing `dist/\n# my-content\n` (committed with normally-readable mode bits). Use `withFakeNpm({ exitCode: 0, logFile })` and the section 1.4 `LOOPX_TEST_AUTOINSTALL_FAULT=gitignore-make-unreadable:<workflow-name>` seam — the seam chmods the committed regular `.gitignore` to mode `000` immediately after commit and before the per-workflow safeguard `lstat`, and is a no-op when the on-disk entry is non-regular so it composes safely with the symlink / FIFO / socket replacement seams. Run `loopx install <source>` with `NODE_ENV=test` and `LOOPX_TEST_AUTOINSTALL_FAULT=gitignore-make-unreadable:<workflow-name>`. Assert: (a) exit code 0 — the safeguard treated the unreadable regular file as a regular file and proceeded to spawn `npm install` without inspecting its contents or permissions; (b) the fake-npm shim log records exactly one invocation with cwd `.loopx/<name>/` (auto-install ran for the workflow despite the unreadable `.gitignore`); (c) no aggregate failure report is emitted on stderr (the unreadable regular file is not a safeguard failure); (d) `.loopx/<name>/.gitignore` still exists as a regular file (verified via `lstat` returning a `S_IFREG` entry type — loopx did not unlink, replace, or otherwise touch the entry); and (e) the on-disk mode bits are still mode `000` from what the seam set (verified via `lstat` reading `0o000` for the user / group / other permission bits on the file) — loopx did not chmod the file readable in order to inspect its contents, did not chmod it for any other reason, and did not append a `node_modules` line that would have required re-opening it for write. **Mode-restoration division of responsibility (per the section 1.4 seam contract).** The seam contract specifies that loopx leaves the file at mode `000` when its own auto-install pass completes — loopx does **not** restore the mode bits during teardown. The test's `afterEach` (or post-assertion cleanup hook) is responsible for chmod'ing the file back to a readable mode (e.g., `0o644`) so that fixture-cleanup logic can read and remove the file; without this harness-side restoration, fixture cleanup will fail with `EACCES` under `process.getuid() !== 0`. The harness must perform the restoration **after** the post-run assertions in (d) and (e) read the on-disk mode bits, otherwise the assertion would observe the restored mode rather than the seam-set mode `000` and the test would silently pass for a buggy implementation. Earlier wording suggested that loopx's own teardown might restore the mode; that has been clarified to remove the contradiction with assertion (e), which would not survive an implementation-side restore. **Conditional on `process.getuid() !== 0`** (root can read mode-`000` files, defeating the test). A buggy implementation that special-cased `.gitignore` content inspection (e.g., reading the file to check whether `node_modules` is already listed before deciding whether to append) would fail (a) with an `EACCES` error during the read, would fail (c) with a safeguard-failure aggregate report, or would fail (e) with the file's mode having been temporarily relaxed to enable the read. Together with T-INST-112a (content-non-inspection axis on a normally-readable fixture), this completes coverage of SPEC 10.10's "does not inspect ... contents or permissions" clause. *(Spec 10.10)*
+
+##### Malformed `package.json`
+
+- **T-INST-113**: Malformed `package.json` (invalid JSON) — warning once, auto-install skipped silently. Single-workflow source with `package.json` containing `{broken`. Use `withFakeNpm`. Run install. Assert: (a) exit code 0 (malformed `package.json` is non-fatal per Spec 3.2/10.6), (b) the shim log is empty (`npm install` not invoked — the skip is silent per Spec 10.10 "does not add a second warning"), (c) stderr contains exactly one `package.json` parse-failure warning for the workflow (from Spec 3.2's existing warning path, not a new auto-install warning), (d) `.loopx/<name>/.gitignore` was not created (safeguard also skipped for the malformed workflow), (e) no aggregate failure report is emitted (skipped-due-to-malformed workflow is not an auto-install failure). *(Spec 10.10, 3.2)*
+- **T-INST-113a**: Malformed `package.json` (unreadable) — same as T-INST-113 but with mode 000. Single-workflow source from a **tarball** (git does not preserve mode 000). Use `withFakeNpm`. Run install. Assert: exit 0, no `npm` invocation, single unreadable-file warning, no `.gitignore` synthesis, no aggregate failure report. **Conditional on `process.getuid() !== 0`.** *(Spec 10.10, 3.2)*
+- **T-INST-113b**: Malformed `package.json` (invalid semver range) — same structure as T-INST-113. Source's `package.json` contains `{ "dependencies": { "loopx": "not-a-range!!!" } }`. Use `withFakeNpm`. Run install. Assert: exit 0, no `npm` invocation, single invalid-semver warning, no `.gitignore` synthesis, no aggregate failure report. *(Spec 10.10, 3.2)*
+- **T-INST-113g**: Malformed `package.json` (`loopx` version field is a **non-string** value) — auto-install skip per SPEC 10.10 malformed-`package.json` rules. Same structure as T-INST-113b but with a non-string range. Source's `package.json` contains `{ "dependencies": { "loopx": 42 } }` (JSON number, not a string). Use `withFakeNpm({ exitCode: 0, logFile })`. Run `loopx install <source>`. Assert: (a) exit 0 (malformed `package.json` is non-fatal per SPEC 3.2 / 10.6), (b) the shim log is empty (`npm install` not invoked — auto-install skipped under SPEC 10.10's malformed-`package.json` rule), (c) stderr contains exactly one invalid-semver / `package.json` warning for the workflow (the SPEC 3.2 warning, not a second auto-install warning per SPEC 10.10 "does not add a second warning for the same underlying failure"), (d) `.loopx/<name>/.gitignore` was not created (safeguard skipped alongside `npm install`), (e) no aggregate failure report (skipped-due-to-malformed workflow is not an auto-install failure), and (f) the workflow is still committed at `.loopx/<name>/` (file-level commit succeeded; only auto-install was skipped). T-INST-113b covers the invalid-string-range path; this test covers the non-string-type path, completing T-VER-09a / T-VER-12c at the auto-install-skip surface. A buggy implementation that gated the SPEC 10.10 skip on `typeof rangeValue === "string" && !semver.validRange(rangeValue)` (rather than "any value that is not a valid semver range, including non-strings") would wrongly proceed to `npm install` here and fail this test. *(Spec 10.10, 3.2)*
+- **T-INST-113d**: Auto-install does **not** skip for an invalid semver range in an ignored dependency field. SPEC 3.2 says workflow-level version checking reads only `dependencies.loopx` and `devDependencies.loopx`; `optionalDependencies.loopx` and `peerDependencies.loopx` are ignored (T-VER-11 / T-VER-11a / T-VER-11b pin the runtime side). SPEC 10.10's "Malformed `package.json`" auto-install skip fires only when the workflow's `package.json` is unreadable, contains invalid JSON, or has an invalid semver range **in a field that workflow-level version checking reads**. An invalid semver range in an ignored field must not trigger the auto-install skip. Single-workflow source with `package.json = { "optionalDependencies": { "loopx": "not-a-range!!!" } }` (no `dependencies.loopx`, no `devDependencies.loopx`). Use `withFakeNpm({ exitCode: 0, logFile })`. Run install. Assert: (a) exit code 0, (b) stderr contains no `package.json` parse / semver / unreadable warning and no auto-install-skip indication (the ignored-field invalid range is invisible at both the version-check tier and the auto-install-skip tier), (c) the fake-npm shim log shows **exactly one** invocation for the workflow (auto-install ran), and (d) `.gitignore` safeguard was synthesized (safeguard ran alongside `npm install`). Together with T-VER-11a (runtime ignores invalid `optionalDependencies.loopx`), this pins down the symmetric rule at install time — an implementation that wrongly routed all `package.json` parse anomalies into the auto-install-skip path would fail this test. *(Spec 10.10, 3.2)*
+- **T-INST-113d2**: Auto-install does **not** skip for an invalid semver range in `peerDependencies.loopx`. Companion to T-INST-113d (`optionalDependencies` invalid-range ignored at the auto-install-skip tier); this test extends the same coverage to the second ignored dependency field, `peerDependencies`. Per SPEC 3.2, workflow-level version checking reads only `dependencies.loopx` and `devDependencies.loopx`; `peerDependencies.loopx` is not one of the enumerated fields. SPEC 10.10's malformed-`package.json` auto-install-skip rule therefore must not fire for an invalid semver range in `peerDependencies.loopx`. Single-workflow source with `package.json = { "peerDependencies": { "loopx": "not-a-range!!!" } }` (no `dependencies.loopx`, no `devDependencies.loopx`). Use `withFakeNpm({ exitCode: 0, logFile })`. Run install. Assert: (a) exit code 0, (b) stderr contains no `package.json` parse / semver / unreadable warning and no auto-install-skip indication (the ignored-field invalid range is invisible at both the version-check tier and the auto-install-skip tier), (c) the fake-npm shim log shows **exactly one** invocation for the workflow (auto-install ran — `peerDependencies.loopx` is outside the SPEC 3.2 enumerated set, so its invalidity does not gate auto-install), and (d) `.gitignore` safeguard was synthesized (safeguard ran alongside `npm install`). Together with T-VER-11b2 (runtime), T-VER-13b2 (install-time version-check tier with `--no-install`), and this test (auto-install-skip tier with `withFakeNpm`), all three observation surfaces are pinned for invalid `peerDependencies.loopx`, mirroring the existing three-surface coverage for invalid `optionalDependencies.loopx` (T-VER-11a / T-VER-13a / T-INST-113d). A buggy implementation that wrongly routed all invalid semver ranges anywhere in `package.json` into the auto-install-skip path would fail this test. *(Spec 10.10, 3.2)*
+- **T-INST-113e**: Auto-install does **not** skip when `dependencies.loopx` is valid-and-satisfied but `devDependencies.loopx` is an invalid semver range. Per SPEC 3.2 precedence, `dependencies` wins over `devDependencies` when present (T-VER-10b proves `devDependencies` is fully invisible when `dependencies.loopx` is valid and satisfied). Since `devDependencies.loopx` is not read, its invalidity must not surface as a warning and must not trigger the auto-install skip. Single-workflow source with `package.json = { "dependencies": { "loopx": "<running-version>" }, "devDependencies": { "loopx": "not-a-range!!!" } }` where `<running-version>` is the actually-running loopx version (or a `*` range). Use `withFakeNpm({ exitCode: 0, logFile })`. Run install. Assert: (a) exit code 0, (b) no version mismatch / invalid-semver / parse warning on stderr, (c) exactly one `npm` invocation for the workflow (auto-install ran), and (d) `.gitignore` safeguard was synthesized. This is the install-time counterpart to T-VER-10b (runtime) and closes a subtle gap — an implementation that validates every `*.loopx` field found in `package.json` (even ones precedence-skipped) could wrongly emit an invalid-semver warning and skip auto-install here. *(Spec 10.10, 3.2)*
+- **T-INST-113f**: Auto-install does **not** skip when a non-`loopx` dependency has an invalid semver range. Companion to T-VER-11d / T-VER-13d. SPEC 3.2 restricts version validation to `dependencies.loopx` / `devDependencies.loopx`; an invalid range on any other dependency entry must not be treated as a `package.json` failure and must not trigger the SPEC 10.10 malformed-`package.json` auto-install skip. Single-workflow source with `index.sh` and a top-level `package.json` containing `{ "dependencies": { "not-loopx": "not-a-range!!!" } }` (no `loopx` field anywhere). Use `withFakeNpm({ exitCode: 0, logFile })`. Run `loopx install <source>`. Assert: (a) exit code 0, (b) no `package.json`-related warnings on stderr (no invalid-semver warning, no parse warning, no auto-install-skip indication), (c) the fake-npm shim log records **exactly one** invocation for the workflow (auto-install ran — invalid ranges on unrelated dependencies must not short-circuit auto-install), and (d) `.gitignore` safeguard was synthesized alongside `npm install`. An implementation that wrongly routed "any invalid semver anywhere in `package.json`" into the SPEC 10.10 skip path would fail this test. *(Spec 10.10, 3.2)*
+- **T-INST-113c**: Multi-workflow install continues past a malformed-`package.json` workflow. Per SPEC 10.10 "Malformed `package.json`": the malformed-`package.json` workflow is skipped silently for auto-install, is **not** treated as an aggregate failure, and other workflows still proceed. Create a multi-workflow source with **two** committed workflows: `alpha/` with `alpha/index.sh` and a **malformed** `alpha/package.json` (invalid JSON, e.g., `{broken`), and `beta/` with `beta/index.sh` and a **valid** `beta/package.json` (e.g., `{ "name": "beta", "version": "1.0.0" }`). Use `withFakeNpm({ exitCode: 0, logFile })`. Run `loopx install <source>`. Assert: (a) exit code 0 — not 1, because the skipped-due-to-malformed workflow is not an auto-install failure per SPEC 10.10, (b) the fake-npm shim log records **exactly one** invocation — for `beta/` (cwd = `.loopx/beta/`, argv = `["install"]`), and **zero** invocations for `alpha/`, (c) stderr contains exactly **one** `package.json` parse-failure warning for `alpha/` (the single existing SPEC 3.2 warning — no second auto-install warning), (d) no `.gitignore` synthesis occurred for `alpha/` (safeguard is skipped alongside `npm install` for malformed-`package.json` workflows), (e) `.gitignore` synthesis occurred for `beta/` (the safeguard ran fresh for the valid workflow), (f) **no aggregate failure report** is emitted on stderr — the skipped-due-to-malformed workflow is not a failure and triggers no report, and (g) both workflow directories are committed at `.loopx/alpha/` and `.loopx/beta/`. T-INST-113 / T-INST-113a / T-INST-113b cover the malformed-`package.json` skip behavior only in single-workflow cases; this test closes the gap by exercising the SPEC 10.10 continuation rule — that other workflows still proceed when one is skipped — and the negative "no aggregate failure" assertion that the single-workflow tests cannot exercise. *(Spec 10.10, 3.2)*
+- **T-INST-113c2**: Multi-workflow install continues past a malformed-`package.json` workflow regardless of the underlying malformation cause. Companion to T-INST-113c which covers only the **invalid-JSON** cause; this test extends the SPEC 10.10 continuation rule to the remaining SPEC 3.2 / 10.10 malformed-`package.json` causes — **unreadable `package.json`**, **invalid semver range in `dependencies.loopx`**, and **non-string `dependencies.loopx` value** — by parameterizing the same two-workflow continuation fixture over each cause variant. The single-workflow tests T-INST-113a (unreadable), T-INST-113b (invalid semver), and T-INST-113g (non-string `loopx` value) pin the per-cause auto-install-skip behavior in isolation, but they do not exercise the SPEC 10.10 "other workflows still proceed" clause for any cause other than invalid-JSON. A buggy implementation that routed the four SPEC 3.2 / 10.10 malformed-`package.json` causes through separate code paths and got the multi-workflow continuation right only for invalid-JSON would pass T-INST-113c plus the per-cause single-workflow tests yet fail this test for the un-tested causes. **Variants** (each a distinct test instance — three sub-cases): **(i) unreadable `alpha/package.json`** — same fixture shape as T-INST-113c but `alpha/package.json` is created with mode `000` after install staging (or via the tarball source variant from T-INST-113a so the mode is preserved through the install pipeline); **conditional on `process.getuid() !== 0`** (per T-INST-113a's gating); **(ii) invalid semver range in `alpha/package.json`** — `alpha/package.json` contains `{ "dependencies": { "loopx": "not-a-range!!!" } }` (matching T-INST-113b's range); **(iii) non-string `dependencies.loopx` value in `alpha/package.json`** — `alpha/package.json` contains `{ "dependencies": { "loopx": 42 } }` (matching T-INST-113g's non-string range). For each variant, `beta/` always has the same valid `beta/package.json` as T-INST-113c (`{ "name": "beta", "version": "1.0.0" }`). Use `withFakeNpm({ exitCode: 0, logFile })`. Run `loopx install <source>`. **Per-variant assertions** mirror T-INST-113c's seven assertions: (a) exit code 0 (skipped-due-to-malformed workflow is not an auto-install failure per SPEC 10.10), (b) the fake-npm shim log records **exactly one** invocation — for `beta/` (cwd = `.loopx/beta/`, argv = `["install"]`), and **zero** invocations for `alpha/`, (c) stderr contains exactly **one** SPEC 3.2 `package.json` warning for `alpha/` matching the variant's cause (unreadable / invalid-semver / invalid-semver-non-string — same warning categories that T-INST-113a / T-INST-113b / T-INST-113g pin in single-workflow form; **no second auto-install warning** for any variant), (d) no `.gitignore` synthesis occurred for `alpha/` (safeguard is skipped alongside `npm install` for the malformed workflow regardless of cause), (e) `.gitignore` synthesis occurred for `beta/` (the safeguard ran fresh for the valid workflow regardless of `alpha/`'s cause), (f) **no aggregate failure report** is emitted on stderr (the skipped-due-to-malformed workflow is not a failure and triggers no report, regardless of cause), and (g) both workflow directories are committed at `.loopx/alpha/` and `.loopx/beta/` (file-level commit succeeds for the malformed workflow regardless of cause; only auto-install is skipped). Together with T-INST-113c (invalid-JSON cause × multi-workflow continuation) and T-INST-113a / T-INST-113b / T-INST-113g (per-cause single-workflow auto-install-skip), this closes the SPEC 10.10 "other workflows still proceed" rule across the full enumerated SPEC 3.2 malformed-`package.json` cause set. *(Spec 10.10, 3.2)*
+
+##### `npm install` Failures
+
+- **T-INST-114**: `npm install` non-zero exit — aggregate report, continue processing remaining workflows, final exit 1. Multi-workflow source: `alpha/`, `beta/`, `gamma/` each with `package.json`. Use `withFakeNpm({ exitCodeByWorkflow: { beta: 1, gamma: 1 }, logFile })` so the shim exits non-zero when invoked in `.loopx/beta/` or `.loopx/gamma/`, regardless of their position in the auto-install order; `alpha/` falls back to the default `exitCode` of 0. Workflow-name keying avoids assuming an auto-install order that SPEC 10.10 explicitly leaves implementation-defined (cf. T-INST-112c's rationale). The two-failing-workflow form is what makes continuation-after-failure observable regardless of the implementation-defined auto-install order: with one failure only, a pass that aborted at the first failure would still invoke `npm install` for all workflows whenever the failing workflow is last in the auto-install order, so the "all three invoked" assertion passes vacuously. With **two** failing workflows, an implementation that aborted at the first failure would invoke `npm install` for at most one of `{beta, gamma}` (whichever came first), and the three-invocations assertion below catches that. Run `loopx install <source>`. Assert: (a) exit code 1, (b) shim log records **three** invocations total and **the set** of invocation cwds is exactly `{ .loopx/alpha/, .loopx/beta/, .loopx/gamma/ }` — all three workflows were invoked. Because `beta/` and `gamma/`'s failures did not abort the pass, every workflow's `npm install` ran regardless of the auto-install order; this proves SPEC 10.10's "proceeds with the next workflow" contract without relying on a specific ordering. (c) stderr contains an aggregate failure report listing **both** `beta/` and `gamma/` as `npm install` non-zero-exit failures — a pass that aborted at the first failure would list at most one of them. (d) `alpha/` is not listed, (e) all three workflow directories are committed at `.loopx/<name>/` — the non-zero npm exit does **not** roll back committed workflow files (Spec 10.10 "Dependency-install failures do not roll back the file-level install"). *(Spec 10.10)*
+- **T-INST-114a**: `npm` spawn failure — aggregate report, continue processing later workflows, final exit 1. Same three-workflow source. Use `withFakeNpm({ spawnFailure: true, logFile })` — the shim file is not created, so spawning `npm` fails with `ENOENT`. Run install. Assert: (a) exit code 1, (b) log shows zero invocations (spawn itself failed — the shim never ran), (c) stderr aggregate failure report lists all three workflows (each got its own spawn failure), (d) all three workflow directories still committed. This distinguishes spawn-failure (Spec 10.10 "`npm` is not on `PATH`") from non-zero-exit (T-INST-114). *(Spec 10.10)*
+- **T-INST-114c**: `npm install` spawn failure does not skip the `.gitignore` safeguard — synthesized `.gitignore` files remain on disk for each affected workflow. SPEC 10.10 specifies that the safeguard runs **immediately before** spawning `npm install`: "Immediately before spawning `npm install` in a workflow directory, loopx checks for a top-level `.gitignore` ... If none exists, loopx creates one containing the single line `node_modules`." Because the safeguard runs before the spawn attempt, a downstream spawn failure must not unwind the safeguard — the `.gitignore` was already synthesized when the spawn was attempted. T-INST-114a covers the spawn-failure / aggregate-failure-report / continue-processing branches but does not assert that the safeguard ran for each affected workflow. A buggy implementation that re-ordered the safeguard / spawn sequence (synthesizing `.gitignore` only after a successful `npm install`, or rolling back the safeguard on spawn failure) would pass T-INST-114a while violating SPEC 10.10's ordering. Same three-workflow source as T-INST-114a (`alpha/`, `beta/`, `gamma/`, each with `package.json`) — but ensure **none** of the workflow source trees include a pre-existing `.gitignore`, so the safeguard must synthesize one. Use `withFakeNpm({ spawnFailure: true, logFile })`. Run `loopx install <source>`. Assert: (a) exit code 1 (spawn-failure aggregate failure, same as T-INST-114a), (b) shim log records zero invocations (spawn never reached the shim), (c) the aggregate failure report on stderr lists all three workflows as spawn failures, (d) all three workflow directories committed under `.loopx/<name>/`, and (e) **for each of `.loopx/alpha/.gitignore`, `.loopx/beta/.gitignore`, `.loopx/gamma/.gitignore`**: the file exists with content exactly `node_modules` (optionally with a single trailing newline — implementation-defined, mirroring T-INST-112's content assertion). The safeguard ran before each per-workflow spawn attempt, so all three `.gitignore` files were synthesized even though every spawn failed afterward. T-INST-112 pins down the safeguard-before-spawn ordering on the success path via the `recordGitignoreAtStart` shim hook; this test pins down the ordering on the **spawn-failure** path via the externally observable `.gitignore`-on-disk surface (the shim never runs, so the in-shim hook from T-INST-112 is unavailable here). *(Spec 10.10)*
+- **T-INST-114d**: Mixed auto-install failure modes in a single multi-workflow install — aggregate report distinguishes failure categories per workflow, continues processing remaining workflows, and excludes successful workflows from the report. SPEC 10.10's aggregate-failure-report contract specifies that loopx "continues processing remaining workflows" past any individual auto-install failure and that the final aggregate report identifies each failed workflow with its underlying cause; the four-workflow mixed-failure case pins down that the **failure category is preserved per workflow** rather than collapsed into a generic "auto-install failed" entry, and that all three normatively-enumerated failure categories (`.gitignore` write failure from SPEC 10.10's safeguard clause, `npm install` non-zero exit from SPEC 10.10's "non-zero exit" branch, `npm install` spawn failure from SPEC 10.10's "`npm` is not on `PATH`" branch) appear together without one displacing or aliasing another. T-INST-112c covers `.gitignore` write failure in isolation, T-INST-114 covers `npm install` non-zero exit in isolation, T-INST-114a / T-INST-114b cover spawn failure (the latter selectively per workflow), but the **simultaneous mixed-cause case** is uncovered — a buggy implementation that handled each failure category through a shared aggregate-failure code path could collapse the cause-distinction (e.g., reporting all three failures as "npm install failed for X" regardless of whether spawn or non-zero-exit or safeguard-write was the actual cause) and pass each isolated test while violating the per-workflow cause-preservation contract here. **Setup.** Multi-workflow source with **four** workflows: `alpha/`, `beta/`, `gamma/`, and `delta/`, each with `index.sh` and a top-level `package.json` and **no** pre-existing `.gitignore` (so the safeguard must synthesize one for each). Configure faults: `LOOPX_TEST_AUTOINSTALL_FAULT=gitignore-write-fail:alpha;npm-spawn-fail:gamma` (semicolon-separated combination per section 1.4 — `alpha/`'s safeguard write fails, `gamma/`'s spawn fails before reaching the shim). Use `withFakeNpm({ exitCodeByWorkflow: { beta: 1 }, logFile })` so the shim exits non-zero when invoked in `.loopx/beta/` and exits 0 in `.loopx/delta/`; the shim never runs for `alpha/` (skipped due to safeguard failure per SPEC 10.10) and never runs for `gamma/` (spawn-fault-injected). Run `loopx install <source>`. Assert: (a) exit code 1 (aggregate failure due to three distinct failures), (b) the shim log records exactly two invocations, with cwds equal to `{ .loopx/beta/, .loopx/delta/ }` — `beta/` reached the shim and exited non-zero, `delta/` reached the shim and succeeded, `alpha/` and `gamma/` did not reach the shim, (c) the aggregate failure report on stderr lists **all three** failed workflows (`alpha/`, `beta/`, `gamma/`), (d) **the failure category preserved per workflow is correct**: `alpha/` is identified as a `.gitignore` write failure (matching the category from T-INST-112c), `beta/` is identified as an `npm install` non-zero-exit failure (matching the category from T-INST-114), `gamma/` is identified as an `npm install` spawn failure (matching the category from T-INST-114a) — the three categories are observably distinct in the aggregate report (even if the exact wording is implementation-defined, the test pattern-matches per workflow against either a category-specific phrase like "spawn failure" / "non-zero exit" / "`.gitignore` write failure", or a normalized error-class field), (e) `delta/` is **not** listed in the aggregate failure report (its safeguard succeeded, its `npm install` ran and exited 0; successful workflows are excluded from the report per SPEC 10.10), (f) **no rollback** of any committed workflow files: `.loopx/alpha/index.sh`, `.loopx/alpha/package.json`, `.loopx/beta/...`, `.loopx/gamma/...`, and `.loopx/delta/...` all exist on disk with their intended contents (per SPEC 10.10 / T-INST-117 / T-INST-112d), (g) `.gitignore` synthesis state per workflow: `alpha/` has no synthesized `.gitignore` (the safeguard failed before write), `beta/` / `gamma/` / `delta/` each have a synthesized `.gitignore` with content `node_modules` (the safeguard succeeded for those three, even though `gamma/`'s subsequent `npm install` spawn was fault-injected — per T-INST-114c, the safeguard runs before the spawn attempt so a downstream spawn failure does not unwind the safeguard), and (h) **continuation across mixed failures**: with three failures distributed across the run, an implementation that aborted the pass at the first failure would fail to record at least two of the three failures (missing entries in the aggregate report) and would skip `delta/` entirely (no shim invocation for `delta/`). The four-workflow mix and the three-category distinction together exercise the SPEC 10.10 "continue processing remaining workflows" contract under the worst case where each failure mode arrives at a different stage of the auto-install pipeline (safeguard-write, spawn, non-zero-exit). **No assertion on cross-workflow auto-install order is made**: SPEC 10.10 explicitly leaves the cross-workflow auto-install order implementation-defined and not an external conformance contract, so the test does not pin which workflow is processed first; the assertions are framed in terms of per-workflow outcomes (set membership on shim-log cwds, set membership and category-tag membership on the aggregate-report entries) rather than sequential observation. *(Spec 10.10, 12)*
+- **T-INST-114b**: `npm install` spawn failure on one workflow does not prevent `npm install` on subsequent workflows. Multi-workflow source: `alpha/`, `beta/`, `gamma/` each with a top-level `package.json`. Drive the per-workflow spawn-failure via the `LOOPX_TEST_AUTOINSTALL_FAULT=npm-spawn-fail:beta,gamma` seam (section 1.4) so loopx's spawn hook simulates `ENOENT` for **both** `beta/` and `gamma/`, while the ordinary `withFakeNpm({ exitCode: 0, logFile })` shim continues to satisfy real spawns for `alpha/`. Using two failing workflows (rather than one) makes continuation-after-failure observable regardless of the implementation-defined auto-install order: SPEC 10.10 explicitly leaves cross-workflow order implementation-defined, so with a single failing workflow an implementation that aborted the pass at the first spawn failure could still pass if the failing workflow is processed last. With **two** failing workflows an implementation that aborted at the first failure would invoke the shim for at most one non-failing workflow, so asserting that the shim ran only for `alpha/` and that both `beta/` and `gamma/` appear in the aggregate report catches any implementation that stops at the first spawn failure. Run `loopx install <source>`. Assert: (a) exit code 1, (b) the shim log records exactly one invocation — for `alpha/`, and **none** for `beta/` or `gamma/` (the seam short-circuits the spawn for both before the shim runs), (c) the aggregate failure report on stderr lists **both** `beta/` and `gamma/` as `npm install` spawn-failures — a pass that aborted at the first failure would list at most one of them. (d) `alpha/` is not listed. This test uses the seam — rather than a per-invocation shim configuration — because once a shim process starts, the spawn itself has already succeeded; a black-box fake `npm` cannot deterministically produce `ENOENT` for one invocation while handing off control to the shim for others. Together with T-INST-114a (all-invocations spawn failure via PATH control), this test closes the per-workflow spawn-failure branch of SPEC 10.10 "continue processing later workflows". *(Spec 10.10)*
+
+##### Environment Purity
+
+- **T-INST-115**: `npm install` inherits loopx's own `process.env` **unchanged** — positive parity for ordinary inherited vars, plus absence of injected-only vars. Per SPEC 10.10 "The `npm install` child inherits loopx's own `process.env` unchanged. `LOOPX_*` protocol variables, `RunOptions.env`, and env-file entries are not injected." Run this test with loopx's inherited environment explicitly scrubbed of any pre-existing `LOOPX_*` names so the absence assertions are meaningful. Spawn loopx with a controlled inherited environment: `MYVAR=inherited`, `PWD=<project-root>` (the absolute path of the project the install runs from — set explicitly in loopx's inherited environment so the assertion is independent of any shell-level rewrite that might otherwise occur in interactive shells), a base `PATH=/known/test/path:/usr/bin:/bin`, and a specific `TMPDIR=/tmp/known-loopx-tmp` (distinct from the system default — pick a real existing directory for TMPDIR so both loopx and the shim can run). Use `withFakeNpm({ logFile })` which prepends a shim directory to `PATH` for the duration of the test (so `<fake-npm-shim-dir>` becomes `PATH`'s first segment). Record the resulting effective inherited `PATH` as `${SHIM_DIR}:/known/test/path:/usr/bin:/bin` — that is the exact string loopx itself inherits. Create a global env file with `INJECTED_GLOBAL=yes` and a `PATH=/fake/env-file-path` override. The shim's log records the child's `MYVAR`, `INJECTED_GLOBAL`, `PATH`, `TMPDIR`, `PWD`, and `LOOPX_*` variables. **Raw-env recording required for `PWD`.** Per the helper-section "Raw-env recording for PWD-sensitive assertions" rule above, the shim's per-invocation log MUST record `PWD` via a raw-env mechanism that observes the process's inherited environment before any shell-startup `$PWD` rewrite — i.e., a Node/Bun shim reading `process.env.PWD` directly (the recommended path; Node and Bun do not rewrite the inherited `PWD` to `getcwd()` on startup), or, in a Bash shim, an `exec env` / direct `/proc/self/environ` read taken from the first executable line before Bash's `cmd_init()` rewrite. Reading `${PWD}` (or `printenv PWD` after Bash has initialized) inside a Bash shim records Bash's shell-rewritten value (equal to the shim's cwd `.loopx/<workflow>/`), not loopx's inherited `PWD`, and would falsely fail (f) below on a conforming implementation. Run `loopx install <source>`. Assert: (a) `MYVAR=inherited` — ordinary inherited vars reach the child, (b) **no** `INJECTED_GLOBAL` — env-file entries are not injected, (c) **no loopx-injected protocol variables** (`LOOPX_BIN`, `LOOPX_PROJECT_ROOT`, `LOOPX_WORKFLOW`, `LOOPX_WORKFLOW_DIR`, `LOOPX_TMPDIR`) — script-execution-context concerns are scoped to spawned scripts, not the auto-install child, (d) `PATH` in the npm child's env equals loopx's own inherited `PATH` byte-for-byte (i.e., `${SHIM_DIR}:/known/test/path:/usr/bin:/bin`) — the env-file's `PATH=/fake/env-file-path` did **not** reach the child, loopx did **not** prepend, append, rewrite, or reorder `PATH`, and the shim-dir prefix is preserved because it was already present in loopx's inherited environment, (e) `TMPDIR` in the npm child's env equals loopx's inherited `/tmp/known-loopx-tmp` exactly (unchanged; not rewritten to `LOOPX_TMPDIR` or any other path), and (f) `PWD` in the npm child's env (recorded via the raw-env mechanism specified above) equals loopx's inherited `PWD` (`<project-root>`) byte-for-byte — `PWD` is an ordinary inherited variable that reaches the npm child unchanged, **not** rewritten to the npm child's cwd (`.loopx/<workflow>/`) by loopx; per SPEC 10.10's "inherits loopx's own `process.env` unchanged" wording, loopx neither updates `PWD` to the spawn cwd nor strips it. The `PATH` assertion is a "passthrough byte-for-byte" check against loopx's own inherited `PATH` — including the shim-dir prefix — not a check against the pre-shim base `PATH`; either formulation of the assertion must resolve the shim prefix correctly. The `PWD` assertion specifically guards against an implementation that, while otherwise inheriting env unchanged, special-cased `PWD` to track the spawn cwd (a common shell convention that does not apply to non-shell direct spawns of `npm`); the raw-env recording requirement guards against a separate failure mode where a Bash-implemented shim's own `$PWD` rewrite would falsely fail this assertion against a conforming loopx. *(Spec 10.10, 8.3)*
+- **T-INST-115a**: Inherited `LOOPX_*` protocol-variable values reach `npm install` unchanged. SPEC 10.10 says the `npm install` child "inherits loopx's own `process.env` unchanged" and that `LOOPX_*` protocol variables "are not injected." T-INST-115 pins down the "not injected" half by asserting that `LOOPX_*` names are absent from the npm child's env when loopx's own inherited env did **not** contain them. This test pins down the complementary positive case: when loopx **itself** inherits `LOOPX_*` names from the user's environment (because the user happened to set them in their shell, or because a parent loopx invocation in a delegated chain set them), those values must reach the npm child unchanged — loopx must neither scrub them nor overwrite them with its own injected protocol values (`npm install` is not a script-execution context, so the script-protocol-protected tier-1 override rule from SPEC 8.3 does not apply to the auto-install child). Single-workflow source with `index.sh` and a top-level `package.json`. Use `withFakeNpm({ logFile })` so every npm invocation logs its observed env. Spawn `loopx install <source>` with the following values injected into loopx's **inherited** environment (in addition to the standard test-controlled `PATH` / `MYVAR` / `TMPDIR` from T-INST-115): `LOOPX_BIN=/inherited-bin/loopx`, `LOOPX_TMPDIR=/inherited-tmp`, `LOOPX_WORKFLOW=/inherited-workflow`, `LOOPX_PROJECT_ROOT=/inherited-project-root`, `LOOPX_WORKFLOW_DIR=/inherited-workflow-dir`. The values are intentionally implausible / synthetic so a passthrough vs. overwrite is byte-distinguishable (a real run would produce derived paths under `os.tmpdir()` and the project cwd, never literal `/inherited-*` strings). Run install. Assert: (a) exit code 0, (b) the shim log records exactly one invocation, and (c) for each of the five `LOOPX_*` names in the inherited environment, the npm child's env contains the **inherited literal value** byte-for-byte — `LOOPX_BIN === "/inherited-bin/loopx"`, `LOOPX_TMPDIR === "/inherited-tmp"`, `LOOPX_WORKFLOW === "/inherited-workflow"`, `LOOPX_PROJECT_ROOT === "/inherited-project-root"`, `LOOPX_WORKFLOW_DIR === "/inherited-workflow-dir"`. A buggy implementation that scrubbed `LOOPX_*` names before spawning `npm install` (e.g., to "protect" the npm child from leaked protocol context) would produce missing entries and fail (c); an implementation that overwrote them with its own derived script-execution values (e.g., the real injected `LOOPX_PROJECT_ROOT` for the install command's cwd) would produce a different value than `/inherited-project-root` and also fail. Together with T-INST-115, this test distinguishes the "not injected" guarantee (loopx does not ADD protocol variables) from a hypothetical "scrubbed" or "overwritten" misreading (loopx must not REMOVE or REPLACE them either) — both halves are required by SPEC 10.10's "inherits loopx's own `process.env` unchanged" wording. *(Spec 10.10, 8.3)*
+- **T-INST-115b**: Inherited `LOOPX_DELEGATED` reaches `npm install` unchanged. SPEC 13 classifies `LOOPX_DELEGATED` as a **startup-reserved-only** signal that controls loopx's delegation recursion guard (SPEC 3.2's recursion-guard clause): it is consulted at startup to decide whether to delegate, and is set on the delegated child's environment. Crucially, SPEC 13 does **not** classify `LOOPX_DELEGATED` as a script-protocol-protected variable (the protocol-protected names are `LOOPX_BIN`, `LOOPX_PROJECT_ROOT`, `LOOPX_WORKFLOW`, `LOOPX_WORKFLOW_DIR`, `LOOPX_TMPDIR`); the SPEC 8.3 tier-1 override rule does not apply to it. Combined with SPEC 10.10's "the `npm install` child inherits loopx's own `process.env` unchanged" rule, an inherited `LOOPX_DELEGATED` must therefore propagate to the npm child like any ordinary inherited variable — neither scrubbed (because `npm install` is not a script-execution context where leaked protocol context matters) nor overwritten (because `LOOPX_DELEGATED` is not a script-protocol-protected name that loopx must inject). T-INST-115a covers the five script-protocol-protected names; this test closes the gap for the sixth `LOOPX_*` name, the startup-reserved-only `LOOPX_DELEGATED`. Single-workflow source with `index.sh` and a top-level `package.json`. Use `withFakeNpm({ logFile })`. Spawn `loopx install <source>` with `LOOPX_DELEGATED=1` injected into loopx's inherited environment (alongside the standard test-controlled `PATH` / `MYVAR` / `TMPDIR` from T-INST-115). **Important fixture caveat:** `LOOPX_DELEGATED` set in loopx's inherited environment normally **prevents** delegation per SPEC 3.2 / T-DEL-04 — i.e., loopx itself does not re-delegate. That is the point: this test exercises the case where a non-delegating top-level loopx (because `LOOPX_DELEGATED` is set) still spawns the auto-install `npm install` child with the inherited `LOOPX_DELEGATED` reaching the child unchanged. Run install. Assert: (a) exit code 0, (b) the shim log records exactly one invocation, (c) the npm child's observed env contains `LOOPX_DELEGATED === "1"` (literal byte-for-byte, the inherited value), (d) the marker that would prove loopx itself re-delegated does **not** fire (no `node_modules/.bin/loopx` recursion — confirms `LOOPX_DELEGATED` recursion-guard semantics still hold for loopx itself), and (e) no parent / surrounding `LOOPX_DELEGATED` warning on stderr. A buggy implementation that scrubbed `LOOPX_DELEGATED` from the npm child's env would fail (c) — even though (d) would still pass, because the recursion guard fires before delegation; the npm-child-observation surface in (c) is independent. An implementation that overwrote `LOOPX_DELEGATED` with a different value (e.g., setting it on the npm child for some misguided "child is also delegated" reasoning) would also fail (c) byte-for-byte. Together with T-INST-115 (no protocol injection), T-INST-115a (inherited script-protocol-protected names pass through unchanged), and this test (inherited startup-reserved-only `LOOPX_DELEGATED` passes through unchanged), the SPEC 10.10 "inherits loopx's own `process.env` unchanged" rule is pinned down across all `LOOPX_*` names: protocol-protected (T-INST-115a) and the lone startup-reserved-only one (this test). *(Spec 10.10, 13, 3.2)*
+
+##### Signal During `npm install`
+
+- **T-INST-116**: SIGINT during `npm install` forwards to child process group and loopx exits with signal code. Use `withFakeNpm({ sleepSeconds: 30, pidFile, logFile })` (where `pidFile` is an absolute path under the test's own temp directory) — the shim writes its PID to `pidFile`, writes `"ready"` to stderr, then sleeps. Use `runCLIWithSignal` to spawn `loopx install <source>`. `waitForStderr("ready")`, read the shim PID from `pidFile`, then send SIGINT to loopx. Assert: (a) loopx exits with code 130 (128 + SIGINT), (b) the shim's PID no longer appears in the process table (was terminated — verify via `kill -0 <shim-pid>` returning non-zero). *(Spec 10.10, 7.3)*
+- **T-INST-116a**: SIGTERM during `npm install` → exit 143, shim terminated. Same as T-INST-116 with SIGTERM. *(Spec 10.10, 7.3)*
+- **T-INST-116b**: SIGINT during `npm install` — remaining workflows are not processed (no further `npm` invocations **and** no further `.gitignore` synthesis). Multi-workflow source `alpha/`, `beta/`, `gamma/`, **each with `index.sh` + a top-level `package.json` and no pre-existing `.gitignore`** (so the `.gitignore` safeguard would synthesize one per workflow if the auto-install pass ran for that workflow). Use `withFakeNpm({ sleepSeconds: 30, logFile })` so **every** invocation sleeps 30 s; the signal arrives during whichever workflow is processed first in the implementation's auto-install order. The ready-protocol (shim writes `"ready"` to stderr before sleeping) lets the harness synchronize on the first invocation regardless of which workflow name it targets. Run `loopx install <source>` via `runCLIWithSignal`, `waitForStderr("ready")`, then send SIGINT to loopx. Assert: (a) exit 130, (b) the shim log records **exactly one** invocation — whichever workflow was first in the auto-install order — and the other two workflow names are not present in the log, (c) **only the first-processed workflow's directory contains a synthesized `.gitignore`** (per SPEC 10.10's "Immediately before spawning `npm install`" ordering, the safeguard fired once for the workflow whose `npm install` then got interrupted), and (d) **the other two workflow directories do NOT contain a synthesized `.gitignore`** — `.gitignore` synthesis runs under the same trigger as `npm install`, so when the auto-install pass is interrupted, no further safeguard writes occur for unprocessed workflows. The test does not assume or assert which workflow name was first; SPEC 10.10's "remaining committed workflows are not processed (no further `.gitignore` synthesis or `npm install` invocations)" guarantee is pinned down by the "exactly one invocation, exactly one synthesized `.gitignore`" count, independent of the implementation-defined auto-install order. A buggy implementation that continued safeguard writes for remaining workflows even after a signal — while correctly skipping their `npm install` calls — would pass (b) but fail (d). *(Spec 10.10, 7.3)*
+- **T-INST-116b2**: SIGTERM during `npm install` — remaining workflows are not processed (SIGTERM-axis parity for T-INST-116b). SPEC 10.10's "Signals during `npm install`" clause names "SIGINT / SIGTERM" together for the "remaining committed workflows are not processed (no further `.gitignore` synthesis or `npm install` invocations)" guarantee. T-INST-116b covers the SIGINT branch via the `runCLIWithSignal` SIGINT-then-wait pattern; the SIGTERM branch is the structurally equivalent counterpart and must hold the same contract. T-INST-116a / T-INST-116c–116g cover SIGTERM termination of the active npm child (basic termination, SIGKILL escalation, process-group propagation) but do not assert that SIGTERM also blocks **remaining workflows**' processing — those tests use single-workflow or any-workflow-count fixtures and assert on child-termination behavior, not on the multi-workflow no-further-processing guarantee. A buggy implementation that correctly terminated the active npm child on SIGTERM (passing T-INST-116a / 116c / 116e) but continued processing the remaining workflows after the SIGTERM-induced exit (e.g., a code path that skipped the "remaining workflows are not processed" branch only for SIGTERM, or that fired the safeguard write loop on a SIGTERM-handler path different from SIGINT's) would pass T-INST-116b but fail this test. Use the same multi-workflow fixture and same `withFakeNpm({ sleepSeconds: 30, logFile })` shim as T-INST-116b. Run `loopx install <source>` via `runCLIWithSignal`, `waitForStderr("ready")`, then send **SIGTERM** to loopx. Assert: (a) loopx exits with code **143** (128 + 15 for SIGTERM), (b) the shim log records **exactly one** invocation — whichever workflow was first in the auto-install order — and the other two workflow names are not present in the log, (c) **only the first-processed workflow's directory contains a synthesized `.gitignore`** (per SPEC 10.10's "Immediately before spawning `npm install`" ordering, the safeguard fired once for the workflow whose `npm install` then got interrupted), (d) **the other two workflow directories do NOT contain a synthesized `.gitignore`** — `.gitignore` synthesis runs under the same trigger as `npm install`, so when the auto-install pass is interrupted by SIGTERM no further safeguard writes occur for unprocessed workflows, and (e) all three committed workflow directories (`alpha/`, `beta/`, `gamma/`) still exist on disk with their committed workflow files (`index.sh`, `package.json`) byte-for-byte from the source — committed workflow files are not rolled back under SPEC 10.10's signal-termination clause. As with T-INST-116b, the test does not assume or assert which workflow name was first; the order-independence is preserved by keying assertions on "exactly one invocation, exactly one synthesized `.gitignore`" rather than hard-coded ordering. *(Spec 10.10, 7.3)*
+- **T-INST-116c**: SIGKILL escalation when the `npm install` child ignores SIGTERM beyond the 5-second grace period. SPEC 10.10 "Signals during `npm install`" states: "the section 7.3 grace period and SIGKILL escalation rules apply by analogy" — i.e., after loopx forwards the signal to the npm child's process group, it waits 5 seconds for the group to exit and then sends SIGKILL. T-INST-116 / T-INST-116a cover the clean-exit path (the shim sleeps passively and is terminated by the forwarded signal); this test covers the escalation path. Configure `withFakeNpm` so the shim installs a SIGTERM trap that ignores the signal (equivalent to the `signal-trap-ignore` fixture in section 2.4), writes its PID to `pidFile`, writes `"ready"` to stderr, then sleeps indefinitely: `withFakeNpm({ sleepSeconds: 30, trapSignals: ["TERM", "INT"], pidFile, logFile })` (the `trapSignals` flag installs `trap '' TERM INT` in the shim's Bash preamble; `pidFile` is the alive-shim PID surface from the helper contract). Run `loopx install <multi-workflow source>` via `runCLIWithSignal`. Wait for `"ready"` on stderr, read the shim PID from `pidFile`, then send SIGTERM to loopx. Assert: (a) loopx waits approximately 5 seconds before the shim is terminated (the grace-period window — the test may allow a tolerance of 4–7 seconds to account for scheduling jitter), (b) after that window, the shim process is no longer running (verified via `kill -0 <shim-pid>` returning non-zero, indicating SIGKILL took effect since the shim was trapping/ignoring SIGTERM), (c) loopx exits with code 143 (128 + 15 for SIGTERM), and (d) the aggregate-failure-report branch from SPEC 10.10 is not triggered (the install was interrupted by a signal, not by a non-zero npm exit). This pins down that the SPEC 7.3 "5 seconds, then SIGKILL" escalation applies identically to the `npm install` child. `@flaky-retry(2)` due to the real-time 5-second wait. *(Spec 10.10, 7.3)*
+- **T-INST-116d**: SIGINT during `npm install` does not clean partial `node_modules/` state already produced by the interrupted install. Single-workflow source with top-level `package.json`. Use `withFakeNpm({ createFiles: ["node_modules/partial-file"], sleepSeconds: 30, logFile })` so the shim creates `node_modules/partial-file`, writes `"ready"` to stderr, then sleeps. Run `loopx install <source>` via `runCLIWithSignal`, wait for `"ready"`, send SIGINT, and assert: (a) loopx exits 130, and (b) `.loopx/<name>/node_modules/partial-file` still exists after loopx exits. Per SPEC 10.10, partial `node_modules/` state produced before interruption is not cleaned up by loopx. *(Spec 10.10, 7.3)*
+- **T-INST-116d2**: SIGTERM during `npm install` does not clean partial `node_modules/` state already produced by the interrupted install (SIGTERM-axis parity for T-INST-116d). SPEC 10.10's "Signals during `npm install`" clause says "Partial `node_modules/` state produced before interruption is not cleaned up by loopx" without distinguishing SIGINT and SIGTERM — the same rule applies to both signals. T-INST-116d covers the SIGINT branch; the SIGTERM branch is the structurally equivalent counterpart and must hold the same contract. A buggy implementation that left partial `node_modules/` in place on SIGINT (passing T-INST-116d) but cleaned it up on SIGTERM (e.g., a SIGTERM-handler path that mistakenly invoked an `rm -rf .loopx/<name>/node_modules` cleanup branch loopx does not own) would pass T-INST-116d and fail this test. Use the same single-workflow fixture and same `withFakeNpm({ createFiles: ["node_modules/partial-file"], sleepSeconds: 30, logFile })` shim as T-INST-116d. Run `loopx install <source>` via `runCLIWithSignal`, wait for `"ready"`, send **SIGTERM**, and assert: (a) loopx exits with code **143** (128 + 15 for SIGTERM), and (b) `.loopx/<name>/node_modules/partial-file` still exists after loopx exits — the partial `node_modules/` state produced by the interrupted npm child is preserved on disk under SIGTERM termination just as it is under SIGINT. *(Spec 10.10, 7.3)*
+- **T-INST-116e**: Signal during `npm install` is forwarded to the npm child's **process group**, not just the npm shim process. Single-workflow source with top-level `package.json`. Use `withFakeNpm({ spawnGrandchild: true, grandchildPidFile, pidFile, sleepSeconds: 30, logFile })` so the shim spawns a long-lived background child, writes the grandchild PID to `grandchildPidFile`, writes its own PID to `pidFile`, writes `"ready"` to stderr, then blocks. Run `loopx install <source>` via `runCLIWithSignal`, wait for `"ready"`, read the shim PID from `pidFile`, send SIGTERM to loopx, and assert: (a) loopx exits with code 143, (b) the npm shim PID is no longer running, and (c) the recorded grandchild PID is also no longer running. This is the auto-install/process-group counterpart to T-SIG-06. *(Spec 10.10, 7.3)*
+- **T-INST-116f**: SIGINT escalation when the `npm install` child traps / ignores SIGINT. SIGINT counterpart to T-INST-116c (SIGTERM escalation). SPEC 10.10 says "SIGINT / SIGTERM received while an `npm install` child is active propagates to the child's process group" and "the section 7.3 grace period and SIGKILL escalation rules apply by analogy" — both signals are subject to the 5-second grace + SIGKILL escalation. T-INST-116c covers the SIGTERM escalation branch; the SIGINT branch is uncovered, mirroring the runtime-script signal-parity gap that T-SIG-05a (runtime SIGINT escalation) closes vs. T-SIG-05 (runtime SIGTERM escalation). A buggy implementation that escalated to SIGKILL only for SIGTERM-trapping npm children — short-circuiting the grace period for SIGINT — would pass T-INST-116c but fail this test. Use the same fixture pattern as T-INST-116c with `trapSignals: ["INT", "TERM"]` and `pidFile` (already in T-INST-116c's setup) so the shim ignores **SIGINT** in addition to SIGTERM and exposes its PID via `pidFile`. Run `loopx install <multi-workflow source>` via `runCLIWithSignal`, wait for `"ready"` on stderr, read the shim PID from `pidFile`, then send **SIGINT** to loopx. Assert: (a) loopx waits approximately 5 seconds before the shim is terminated (4–7 second tolerance, matching T-INST-116c), (b) after that window, the shim process is no longer running (SIGKILL took effect because the shim trapped/ignored SIGINT), (c) loopx exits with code **130** (128 + 2 for SIGINT — the originally-forwarded signal, not the SIGKILL escalation), and (d) the aggregate-failure-report branch from SPEC 10.10 is not triggered (the install was interrupted by a signal, not by a non-zero npm exit). `@flaky-retry(2)` due to the real-time 5-second wait. *(Spec 10.10, 7.3)*
+- **T-INST-116g**: SIGINT during `npm install` is forwarded to the npm child's **process group**, not just the npm shim process. SIGINT counterpart to T-INST-116e (SIGTERM process-group). SPEC 10.10 names "SIGINT / SIGTERM" together as the signals that propagate to the npm child's process group. T-INST-116e covers the SIGTERM branch; the SIGINT branch is uncovered, mirroring the runtime-script signal-parity gap that T-SIG-06a closes vs. T-SIG-06. A buggy implementation that forwarded SIGINT only to the direct npm child (not its process group) would leave the grandchild orphaned and pass T-INST-116e (SIGTERM-only) but fail this test. Use the same fixture pattern as T-INST-116e — `withFakeNpm({ spawnGrandchild: true, grandchildPidFile, pidFile, sleepSeconds: 30, logFile })` — and deliver SIGINT instead of SIGTERM. Run `loopx install <source>` via `runCLIWithSignal`, wait for `"ready"`, read the shim PID from `pidFile`, send SIGINT to loopx, and assert: (a) loopx exits with code 130 (SIGINT), (b) the npm shim PID is no longer running, and (c) the recorded grandchild PID is also no longer running. *(Spec 10.10, 7.3)*
+
+##### Signal During Auto-install Pass — No Active `npm` Child
+
+SPEC 10.10's "Signals during the auto-install pass when no npm child is active" clause defines the no-active-child signal-window contract: SIGINT / SIGTERM observed during the post-commit auto-install pass, when no `npm install` child is currently running, aborts the pass and exits with `128 + signal number`; no further `.gitignore` safeguards or `npm install` children are started; committed workflow files are not rolled back; any `.gitignore` / `node_modules/` side effects completed before the signal observation remain on disk; signal termination suppresses the final auto-install aggregate failure report unless it had already been emitted. The clause enumerates four sub-windows (between sequential workflows; during `.gitignore` safeguard work before spawning npm; after one npm child exits and before the next workflow begins; after a `.gitignore` safeguard failure but before the next workflow). Each sub-window is exercised by its own test using the section 1.4 `LOOPX_TEST_AUTOINSTALL_PAUSE` seam in its **ordinal** form (`between-workflows-after-first`, `pre-spawn-first`, `post-exit-first`, `post-safeguard-failure-first`), which pauses loopx at the named position relative to the implementation's auto-install order long enough for the harness to deliver a signal. The ordinal form is required because SPEC 10.10 explicitly leaves the cross-workflow auto-install order implementation-defined and not an external conformance contract — a name-targeted pause (e.g., `between-workflows:beta`) would assume a specific name appears at a specific position and fail conformance for an implementation that processes workflows in a different deterministic order. All four tests use a multi-workflow source so the "no further workflows are processed after the signal" guarantee is observable; each test reads the parent-observable JSON marker (per the section 1.4 contract) to determine which workflow names appeared at which positions in the implementation's auto-install order, then asserts on the observed `processed` / `current` / `remaining` partition rather than on hard-coded `alpha` / `beta` / `gamma` ordering.
+
+- **T-INST-116h**: SIGINT delivered **between sequential workflows** (the `between-workflows-after-first` ordinal window) — the signal is observed after the *first* workflow's auto-install processing has fully completed and before any further workflow's safeguard begins. Three-workflow source `alpha/`, `beta/`, `gamma/`, each with `index.sh` + a top-level `package.json` and **no** pre-existing `.gitignore` (so the safeguard would synthesize one per workflow if processing reached it). Use `withFakeNpm({ exitCode: 0, logFile })` (the npm shim succeeds quickly; the pause seam is what creates the no-active-child window, not a long-sleeping shim). Allocate a harness-controlled marker path via the test's own temp directory (e.g., `<test-tmp>/autoinstall-pause-marker.json` — outside `$LOOPX_TMPDIR` so it survives loopx's tmpdir cleanup). Spawn `loopx install <source>` via `runCLIWithSignal` with `NODE_ENV=test`, `LOOPX_TEST_AUTOINSTALL_PAUSE=between-workflows-after-first`, and `LOOPX_TEST_AUTOINSTALL_PAUSE_MARKER=<absolute-path-to-marker>` — the seam writes the JSON marker on pause-entry (per the section 1.4 contract) and then pauses for the bounded interval. The harness polls for the marker file's existence, reads and parses the JSON, and extracts: `current` (the upcoming workflow whose safeguard would have run next if the pause ended), `processed` (a single-element array containing the workflow name whose full auto-install processing completed before the pause), and `remaining` (an array of workflow names whose processing has not started). The `processed` array's single element is the *first-processed* workflow regardless of which name it corresponds to — SPEC 10.10 explicitly leaves cross-workflow auto-install order implementation-defined, so the test does not assume any specific ordering. Let `first = processed[0]`; `notReached = [current, ...remaining]` (the two workflow names whose safeguards never ran). After reading the marker, send SIGINT to loopx. Assert: (a) loopx exits with code **130** (128 + 2 for SIGINT), (b) the fake-npm shim log records **exactly one** invocation with cwd `.loopx/<first>/` — `npm install` ran for the first-processed workflow, and was **not** invoked for any workflow name in `notReached` (whose processing was preempted by the signal observation), (c) `.loopx/<first>/.gitignore` exists as a regular file containing exactly `node_modules` (the safeguard synthesis from the first workflow's processing completed before the signal), (d) for each workflow name `w` in `notReached`, `.loopx/<w>/.gitignore` does **not** exist on disk (no further safeguard writes ran after the signal — the upcoming workflow's safeguard was preempted by the pause-then-signal, and the still-`remaining` workflows were never reached), (e) `.loopx/alpha/`, `.loopx/beta/`, `.loopx/gamma/` all exist with their committed workflow files (`index.sh`, `package.json`) byte-for-byte from the source — committed workflow files are **not rolled back**, and (f) **no aggregate failure report** is emitted on stderr — signal termination suppresses the aggregate report (and there were no pre-signal failures to report anyway). The `between-workflows-after-first` window is the cleanest of the four sub-windows because no per-workflow processing is in flight when the signal arrives; assertion (d) catches an implementation that continued safeguard writes after the signal observation, and (b) catches one that continued spawning. The ordinal-window form makes the test order-independent: it conforms regardless of whether the implementation processes workflows in `alpha → beta → gamma`, alphabetic, declaration, or any other deterministic order, because the assertions key off the marker's `processed` / `current` / `remaining` partition rather than hard-coded names. *(Spec 10.10, 7.3)*
+- **T-INST-116i**: SIGINT delivered **during `.gitignore` safeguard work before spawning npm** (the `pre-spawn-first` ordinal window) — the signal is observed during the safeguard's pre-`npm install` window for the *first* workflow, after the safeguard `lstat` dispatch decided what to do but before the `spawn("npm", …)` call. Three-workflow source `alpha/`, `beta/`, `gamma/`, same shape as T-INST-116h. Use `withFakeNpm({ exitCode: 0, logFile })`. Allocate a harness-controlled marker path under the test's own temp directory. Spawn `loopx install <source>` via `runCLIWithSignal` with `NODE_ENV=test`, `LOOPX_TEST_AUTOINSTALL_PAUSE=pre-spawn-first`, and `LOOPX_TEST_AUTOINSTALL_PAUSE_MARKER=<absolute-path-to-marker>` — the seam writes the JSON marker on pause-entry and then pauses loopx during the first-processed workflow's safeguard work, after the `lstat` dispatch decision and before the `spawn("npm", …)` call. The harness polls for the marker, reads the JSON, and extracts: `current` (the workflow whose pre-spawn the seam paused inside — i.e., the first-processed workflow under the implementation's auto-install order), `processed` (an empty array — no workflow has completed processing at the pre-spawn-first focal point), and `remaining` (the two workflow names whose processing has not started). Let `first = current` and `untouched = remaining`. Whether the safeguard's filesystem write (synthesizing `.loopx/<first>/.gitignore`) completed before the pause-entry is implementation-defined: SPEC 10.10's clause "If a synchronous or already-started safeguard operation completes before loopx observes the signal, its side effects remain" allows either ordering for this window. The test must therefore **not** assert on `.loopx/<first>/.gitignore` *non-existence* unconditionally (a buggy or compliant implementation could have written it before the pause-entry, and SPEC 10.10 explicitly permits this). However, the same SPEC 10.10 clause also requires that **side effects completed before the signal observation remain on disk**: if the safeguard write did complete before the pause-entry, the resulting on-disk entry must be preserved unchanged across signal termination. To pin that down without over-specifying which side of the timing window the implementation lands on, the harness — after polling the marker and **before** sending the signal — snapshots `.loopx/<first>/.gitignore` state via a single `lstat` plus content read: (i) whether the entry exists, (ii) if it exists, its `lstat` entry type, and (iii) if it is a regular file, its byte-for-byte content. Then send SIGINT to loopx. Assert: (a) loopx exits with code **130**, (b) the fake-npm shim log records **zero** invocations — the spawn for `first` was preempted by the signal observation during the pre-spawn pause, and the workflows in `untouched` were never reached, (c) for each workflow name `w` in `untouched`, `.loopx/<w>/.gitignore` does **not** exist on disk (no safeguard write reached either of them), (d) `.loopx/alpha/`, `.loopx/beta/`, `.loopx/gamma/` all exist with their committed workflow files byte-for-byte — committed workflow files are not rolled back, (e) **no aggregate failure report** is emitted on stderr (signal termination suppresses it; the only "failure" would have been `first`'s preempted spawn, which is not an auto-install failure), and (f) **the post-exit state of `.loopx/<first>/.gitignore` matches the pre-signal snapshot**: if the snapshot recorded "does not exist", no assertion is made under (f) (the safeguard write may have been preempted mid-flight or never started — either is permitted by SPEC 10.10 for this window); if the snapshot recorded "exists as a regular file with content C", the post-exit `lstat` returns a regular-file entry and the post-exit content equals C byte-for-byte — pinning the SPEC 10.10 "side effects completed before the signal observation remain on disk" rule for the pre-spawn-first window without over-specifying which side of the timing window the safeguard write landed on. A buggy implementation that completed the safeguard write before the pause and then rolled it back, mutated it, or replaced it during signal-driven cleanup would fail (f) on every run where the snapshot recorded an existing entry, even though (a)–(e) would all still pass. The pre-spawn-first window is the most timing-sensitive of the four because the safeguard write may or may not have completed; the test deliberately asserts only on the implementation-required outcomes (no spawns, no aggregate report, no rollback, plus the conditional-snapshot preservation in (f)) and leaves the safeguard's pre-pause side effect implementation-defined per SPEC 10.10. The ordinal-window form makes the test order-independent: it does not assume which workflow is first in the implementation-defined auto-install order. *(Spec 10.10, 7.3)*
+- **T-INST-116j**: SIGTERM delivered **after one npm child exits and before the next workflow begins processing** (the `post-exit-first` ordinal window) — the signal is observed after the *first* workflow's `npm install` child has exited and before the next workflow's safeguard `lstat` runs. SPEC 10.10's no-active-child enumeration explicitly distinguishes this from `between-workflows`: this window targets the gap between the previous workflow's npm-child exit and the next workflow's safeguard start, while `between-workflows-after-first` targets the broader gap after one workflow's full processing. The two windows are normatively the same outcome surface (no active child, no further work allowed) but exercise different state-machine transitions; covering both protects against an implementation that handles one transition correctly and the other incorrectly. Three-workflow source `alpha/`, `beta/`, `gamma/`, same shape as T-INST-116h. Use `withFakeNpm({ exitCode: 0, logFile })`. Allocate a harness-controlled marker path under the test's own temp directory. Spawn `loopx install <source>` via `runCLIWithSignal` with `NODE_ENV=test`, `LOOPX_TEST_AUTOINSTALL_PAUSE=post-exit-first`, and `LOOPX_TEST_AUTOINSTALL_PAUSE_MARKER=<absolute-path-to-marker>` — the seam writes the JSON marker on pause-entry and then pauses loopx just after the first-processed workflow's `npm install` child has exited and before any further per-workflow processing begins. The harness polls for the marker, reads the JSON, and extracts: `current` (the workflow whose `npm install` just exited — i.e., the first-processed workflow under the implementation's auto-install order), `processed` (an empty array — no workflow's processing is classified as fully past at the post-exit-first focal point), and `remaining` (the two workflow names whose processing has not started). Let `first = current` and `notReached = remaining`. After observing the marker, send **SIGTERM** to loopx (this test exercises SIGTERM rather than SIGINT — the signal-symmetry parity case for the no-active-child contract; SPEC 10.10 names "SIGINT / SIGTERM" together for this clause). Assert: (a) loopx exits with code **143** (128 + 15 for SIGTERM), (b) the fake-npm shim log records **exactly one** invocation with cwd `.loopx/<first>/` — `npm install` ran for the first-processed workflow and was not invoked for any workflow name in `notReached`, (c) `.loopx/<first>/.gitignore` exists as a regular file containing exactly `node_modules`, (d) for each workflow name `w` in `notReached`, `.loopx/<w>/.gitignore` does **not** exist on disk (no safeguard write reached them), (e) `.loopx/alpha/`, `.loopx/beta/`, `.loopx/gamma/` all exist with their committed workflow files byte-for-byte (no rollback), and (f) **no aggregate failure report** is emitted on stderr. The SIGTERM-instead-of-SIGINT variant of this test pins down the SPEC 10.10 "SIGINT / SIGTERM" parity for the no-active-child clause — a buggy implementation that handled SIGINT but not SIGTERM in the no-active-child window (or vice versa) would pass T-INST-116h (SIGINT) and fail this test (SIGTERM). The ordinal-window form makes the test order-independent: it does not assume which workflow is first in the implementation-defined auto-install order. *(Spec 10.10, 7.3)*
+- **T-INST-116j2**: SIGINT delivered **after a non-zero `npm install` exit and before the next workflow begins** (the `post-exit-first` ordinal window composed with a non-zero npm exit) — the signal is observed after the *first* workflow's `npm install` child has exited **non-zero** (recording an aggregate-report entry) and before the next workflow's safeguard `lstat` runs. T-INST-116j covers the post-exit-first window with a successful npm exit (no aggregate-report content accumulated when the signal arrives). T-INST-116k covers the no-active-child window after a `.gitignore` **safeguard** failure (the failure entry is recorded by the safeguard short-circuit path, not by an npm exit). The composed npm-non-zero-then-signal case — first workflow's `npm install` runs to completion but exits non-zero (entry recorded in the aggregate), then the signal observed during the post-exit-first window before any further safeguards or spawns — is the structurally distinct npm-failure analogue of T-INST-116k's safeguard-failure setup. SPEC 10.10's signal-termination clause says signal termination "suppresses the final auto-install aggregate failure report unless it had already been emitted"; T-INST-116k pins that down for the safeguard-failure accumulator path, and this test pins it down for the **npm-non-zero-exit accumulator path** — closing the post-npm-child-exit no-active-child window when an aggregate failure has already been recorded. Three-workflow source `alpha/`, `beta/`, `gamma/`, each with `index.sh` + a top-level `package.json` and **no** pre-existing `.gitignore` (so the safeguard would synthesize one per workflow if processing reached it). Use `withFakeNpm({ exitCode: 1, logFile })` — every npm invocation exits non-zero — but the pause-then-signal halts further processing after the first npm child exits, so only one invocation is observed regardless. Allocate a harness-controlled marker path under the test's own temp directory. Spawn `loopx install <source>` via `runCLIWithSignal` with `NODE_ENV=test`, `LOOPX_TEST_AUTOINSTALL_PAUSE=post-exit-first`, and `LOOPX_TEST_AUTOINSTALL_PAUSE_MARKER=<absolute-path-to-marker>` — the seam writes the JSON marker on pause-entry just after the first-processed workflow's `npm install` child has exited (non-zero) and before any further per-workflow processing begins. The harness polls for the marker, reads the JSON, extracts: `current` (the workflow whose `npm install` just exited non-zero — the first-processed workflow under the implementation's auto-install order), `processed` (empty), and `remaining` (the two workflow names whose processing has not started). Let `first = current` and `notReached = remaining`. After observing the marker, send **SIGINT** to loopx. Assert: (a) loopx exits with code **130** (128 + 2 for SIGINT — **not** 1, even though `first`'s npm child exited non-zero and an aggregate-report entry was accumulated; the signal supersedes the aggregate-failure exit code per SPEC 10.10's `128 + signal number` clause), (b) the fake-npm shim log records **exactly one** invocation with cwd `.loopx/<first>/` — `npm install` ran for `first` and was not invoked for any workflow in `notReached` (the workflows in `notReached` were preempted by the signal observation in the post-exit-first window before their safeguards or spawns began), (c) `.loopx/<first>/.gitignore` exists as a regular file containing exactly `node_modules` (the safeguard synthesis from `first`'s processing completed before its npm child ran and exited), (d) for each workflow name `w` in `notReached`, `.loopx/<w>/.gitignore` does **not** exist on disk (no further safeguard writes ran after the signal — `notReached` was never processed), (e) `.loopx/alpha/`, `.loopx/beta/`, `.loopx/gamma/` all exist with their committed workflow files byte-for-byte from the source — committed workflow files are **not rolled back**, even though `first`'s npm install failed and the signal then arrived (no rollback under either trigger), and (f) **no aggregate failure report** is emitted on stderr — the npm-non-zero-exit failure entry was recorded in the accumulator before the signal arrived, and the signal-termination suppression rule prevents the report from being emitted to stderr. Assertion (f) is the load-bearing one: an implementation that emitted the aggregate report at the same point in normal completion (after the auto-install pass finishes) but failed to suppress emission on signal termination when the accumulator held an npm-non-zero entry — while correctly suppressing the same emission when the accumulator held a safeguard-failure entry — would pass T-INST-116j (no failure entries to report) and T-INST-116k (suppression of safeguard-failure aggregate) but fail this test. Together with T-INST-116j (post-exit-first × successful npm exit × SIGTERM) and T-INST-116k (post-safeguard-failure-first × safeguard-failure × SIGINT), this closes the post-npm-child-exit no-active-child window across both pre-signal accumulator states (clean and npm-failure-accumulated). *(Spec 10.10, 7.3)*
+- **T-INST-116j3**: SIGTERM delivered **after a non-zero `npm install` exit and before the next workflow begins** (the `post-exit-first` ordinal window composed with a non-zero npm exit) — SIGTERM-axis parity for T-INST-116j2 on the npm-non-zero-exit-accumulator surface. SPEC 10.10's "Signals during the auto-install pass when no npm child is active" clause names "SIGINT / SIGTERM" together; the no-active-child contract holds for both signals identically, including the aggregate-report-suppression sub-case when the accumulator already holds an npm-non-zero entry. T-INST-116j2 covers the SIGINT axis on this composed window-and-accumulator state; a buggy implementation that suppressed the aggregate report under SIGINT in the npm-non-zero accumulator state but special-cased SIGTERM (e.g., a SIGTERM-handler path that emitted the accumulated report before exiting) would pass T-INST-116j2 and fail this test. Same fixture, seam configuration, and harness pattern as T-INST-116j2: three-workflow source `alpha/`, `beta/`, `gamma/`, each with `index.sh` + a top-level `package.json` and no pre-existing `.gitignore`; `withFakeNpm({ exitCode: 1, logFile })`; `LOOPX_TEST_AUTOINSTALL_PAUSE=post-exit-first` with `LOOPX_TEST_AUTOINSTALL_PAUSE_MARKER=<absolute-path-to-marker>`; harness polls for the marker, extracts `current` / `processed` / `remaining`, lets `first = current` and `notReached = remaining`, then sends **SIGTERM** to loopx instead of SIGINT. Assert: (a) loopx exits with code **143** (128 + 15 for SIGTERM — **not** 1, even though `first`'s npm child exited non-zero and an aggregate-report entry was accumulated; the signal supersedes the aggregate-failure exit code per SPEC 10.10's `128 + signal number` clause), (b) the fake-npm shim log records **exactly one** invocation with cwd `.loopx/<first>/` — no further `npm install` spawns occurred after the signal observation, (c) `.loopx/<first>/.gitignore` exists as a regular file containing exactly `node_modules`, (d) for each workflow name `w` in `notReached`, `.loopx/<w>/.gitignore` does **not** exist on disk, (e) `.loopx/alpha/`, `.loopx/beta/`, `.loopx/gamma/` all exist with their committed workflow files byte-for-byte from the source — committed workflow files are **not rolled back**, and (f) **no aggregate failure report** is emitted on stderr — the npm-non-zero-exit failure entry was recorded in the accumulator before the signal arrived, and the signal-termination suppression rule prevents emission for SIGTERM identically to SIGINT. Assertion (f) is the load-bearing one for the parity contract: an implementation whose suppression rule was conditioned on the signal being SIGINT specifically (rather than the SPEC's SIGINT-or-SIGTERM normative pair) would pass T-INST-116j2 and fail this test. Together with T-INST-116j2 (SIGINT axis), this closes the SPEC 10.10 SIGINT/SIGTERM parity for the post-exit-first × non-zero-npm-exit composed window. *(Spec 10.10, 7.3)*
+- **T-INST-116k**: SIGINT delivered **after a `.gitignore` safeguard failure but before the next workflow** (the `post-safeguard-failure-first` ordinal window) — the signal is observed after the *first* safeguard failure has been recorded in the aggregate report, and before any further workflow's safeguard begins. This window is structurally distinct from the other three because the aggregate report has *already accumulated a failure entry* before the signal arrives; the test must therefore prove that signal termination still suppresses the aggregate report's stderr emission even when the report has accumulated content (per SPEC 10.10 "Signal termination suppresses the final auto-install aggregate failure report unless it had already been emitted" — the **suppression** half of that clause). Three-workflow source `alpha/`, `beta/`, `gamma/`, same shape as T-INST-116h. Use `withFakeNpm({ exitCode: 0, logFile })`. Allocate a harness-controlled marker path under the test's own temp directory. To make the test order-independent, apply the FIFO-replacement FAULT to **all three** workflows so that whichever workflow the implementation processes first will have a FIFO at its `.gitignore` immediately before the safeguard `lstat` and will therefore record a safeguard failure. Combine two seams in a single run: `LOOPX_TEST_AUTOINSTALL_FAULT=gitignore-replace-with-fifo:alpha,beta,gamma` (places a FIFO at the `.gitignore` path of whichever workflow is currently being processed, just before its safeguard `lstat`) **and** `LOOPX_TEST_AUTOINSTALL_PAUSE=post-safeguard-failure-first` (pauses loopx after the first safeguard-failure recording and before any further per-workflow processing begins). The two seams use distinct env-var names so no string-collision concern arises; the FAULT seam fires per workflow as that workflow is processed (so only the first-processed workflow's FIFO is ever placed before the pause-then-signal halts further processing), and the PAUSE seam fires once at the post-safeguard-failure-first focal point. Spawn `loopx install <source>` via `runCLIWithSignal` with `NODE_ENV=test`, the combined seam values, and `LOOPX_TEST_AUTOINSTALL_PAUSE_MARKER=<absolute-path-to-marker>`. The harness polls for the marker, reads the JSON, and extracts: `current` (the workflow whose safeguard just failed — i.e., the first-processed workflow under the implementation's auto-install order), `processed` (an empty array — no workflow's processing succeeded at the post-safeguard-failure-first focal point), and `remaining` (the two workflow names whose processing has not started). Let `failed = current` and `notReached = remaining`. After observing the marker, send SIGINT to loopx. Assert: (a) loopx exits with code **130** (128 + 2 for SIGINT — **not** 1, even though `failed`'s safeguard failed; the signal is the terminal trigger and supersedes the aggregate-failure exit code per SPEC 10.10's `128 + signal number` clause), (b) the fake-npm shim log records **zero** invocations — `failed` was skipped because its safeguard failed (`npm install` does not run for safeguard-failure workflows), and the workflows in `notReached` were preempted by the signal before their safeguards ran (so their FIFO replacements never executed either, since the FAULT seam fires immediately before each workflow's safeguard), (c) `.loopx/<failed>/.gitignore` is **still a FIFO** (verified via `lstat` returning `S_IFIFO`) — loopx did not unlink, replace, or otherwise touch the FIFO entry; the safeguard failure left it unchanged per SPEC 10.10's non-regular branch, (d) for each workflow name `w` in `notReached`, `.loopx/<w>/.gitignore` does **not** exist on disk (the FAULT seam never fired for these workflows because their safeguard `lstat` was never reached, and there was no source `.gitignore` content to materialize), (e) `.loopx/alpha/`, `.loopx/beta/`, `.loopx/gamma/` all exist with their committed workflow files byte-for-byte (no rollback — the safeguard failure does not trigger a rollback per SPEC 10.10's "Committed workflow files are not rolled back" clause, and the signal does not either), and (f) **no aggregate failure report** is emitted on stderr — even though `failed`'s safeguard failure was recorded in the aggregate report's accumulator before the signal, the signal-termination suppression rule prevents the report from being emitted to stderr. The (f) assertion is the load-bearing one for this test: an implementation that emitted the aggregate report at the same point in normal completion (after the auto-install pass finishes) but failed to suppress emission on signal termination would pass tests T-INST-116h / 116i / 116j (where there were no failures to report) and fail this test. The ordinal-window form combined with the FAULT-applied-to-all-workflows pattern makes the test order-independent: whichever workflow is first in the implementation's auto-install order is the one whose safeguard fails, and the other two are never reached regardless of which they are. Together with T-INST-116h / 116i / 116j, the four no-active-child sub-windows of SPEC 10.10's signal clause are all pinned down on the SIGINT axis; T-INST-116m closes the structurally distinct spawn-failure-accumulator state for the same suppression rule. *(Spec 10.10, 7.3)*
+- **T-INST-116m**: SIGINT delivered **after an `npm install` spawn failure but before the next workflow** (the `post-spawn-failure-first` ordinal window) — the signal is observed after the *first* spawn failure has been recorded in the aggregate report, and before any further workflow's safeguard begins. SPEC 10.10's no-active-child clause ("If no `npm install` child is active when the signal is observed — including ...") covers all points in the auto-install pass when no `npm install` child is currently running; the existing tests cover the four illustratively-enumerated SPEC sub-windows (between sequential workflows in T-INST-116h; pre-spawn safeguard work in T-INST-116i; post-npm-child-exit in T-INST-116j / 116j2 / 116j3; post-safeguard-failure in T-INST-116k), but the structurally distinct **spawn-failure-recorded** accumulator state is uncovered: the safeguard for the failing workflow ran to completion (so its `.gitignore` synthesis side effects are on disk per SPEC 10.10's "side effects completed before the signal observation remain on disk" rule), the `spawn("npm", …)` call was attempted and rejected before producing a child process (e.g., the SPEC 10.10 "`npm install` spawn failure (most commonly: `npm` is not on `PATH`)" branch), and the aggregate accumulator holds an `npm-install-spawn-failure` entry rather than a non-zero-exit entry (covered by T-INST-116j2 / T-INST-116j3) or a safeguard-failure entry (covered by T-INST-116k / T-INST-116k2). T-INST-116k pins down the safeguard-failure accumulator path for aggregate-report suppression; this test pins down the spawn-failure accumulator path for the same suppression rule, closing the no-active-child signal surface on the spawn-failure failure class. A buggy implementation that suppressed the aggregate report under SIGINT in the safeguard-failure or non-zero-exit accumulator states but special-cased the spawn-failure accumulator state (e.g., a separate dispatch path for spawn-failure entries that emitted the accumulated report before exiting) would pass T-INST-116k / T-INST-116j2 and fail this test. Three-workflow source `alpha/`, `beta/`, `gamma/`, each with `index.sh` + a top-level `package.json` and **no** pre-existing `.gitignore` (so the safeguard would synthesize one per workflow if processing reached it). Apply `LOOPX_TEST_AUTOINSTALL_FAULT=npm-spawn-fail:alpha,beta,gamma` so that whichever workflow the implementation processes first will fail at the `spawn("npm", …)` step (the seam fires per workflow as that workflow is processed, so only the first-processed workflow's spawn is attempted before the pause-then-signal halts further processing). Allocate a harness-controlled marker path under the test's own temp directory (outside `$LOOPX_TMPDIR`). Spawn `loopx install <source>` via `runCLIWithSignal` with `NODE_ENV=test`, `LOOPX_TEST_AUTOINSTALL_PAUSE=post-spawn-failure-first`, `LOOPX_TEST_AUTOINSTALL_PAUSE_MARKER=<absolute-path-to-marker>`, and the FAULT seam value above. The harness uses `withFakeNpm({ exitCode: 0, logFile })` so that *if* loopx incorrectly reached an unfaulted spawn, the shim would record an invocation; under the FAULT seam the shim is never invoked because the spawn-fail seam returns before `spawn("npm", …)` is actually called. The harness polls for the marker file's existence, reads and parses the JSON, and extracts: `current` (the workflow whose `npm install` spawn just failed — i.e., the first-processed workflow under the implementation's auto-install order), `processed` (an empty array — no workflow's processing succeeded at the post-spawn-failure-first focal point), and `remaining` (an array of workflow names whose processing has not started). Let `failed = current` and `notReached = remaining`. After observing the marker, send SIGINT to loopx. Assert: (a) loopx exits with code **130** (128 + 2 for SIGINT — **not** 1, even though `failed`'s spawn failed; the signal is the terminal trigger and supersedes the aggregate-failure exit code per SPEC 10.10's `128 + signal number` clause), (b) the fake-npm shim log records **zero** invocations — `failed`'s spawn was rejected by the FAULT seam before `spawn("npm", …)` was actually invoked, and the workflows in `notReached` were preempted by the signal observation in the post-spawn-failure-first window before their safeguards or spawns began, (c) `.loopx/<failed>/.gitignore` exists as a regular file containing exactly `node_modules` (the safeguard synthesis from `failed`'s processing completed before its spawn was attempted — the safeguard ran successfully and produced its on-disk side effect; only the spawn step failed), (d) for each workflow name `w` in `notReached`, `.loopx/<w>/.gitignore` does **not** exist on disk (no further safeguard writes ran after the signal — `notReached` was never processed), (e) `.loopx/alpha/`, `.loopx/beta/`, `.loopx/gamma/` all exist with their committed workflow files (`index.sh`, `package.json`) byte-for-byte from the source — committed workflow files are **not rolled back**, even though `failed`'s spawn failed and the signal then arrived (no rollback under either trigger), and (f) **no aggregate failure report** is emitted on stderr — even though `failed`'s spawn-failure was recorded in the aggregate report's accumulator before the signal, the signal-termination suppression rule prevents the report from being emitted to stderr. Assertion (f) is the load-bearing one: an implementation that emitted the aggregate report at the same point in normal completion (after the auto-install pass finishes) but failed to suppress emission on signal termination when the accumulator held a spawn-failure entry — while correctly suppressing the same emission when the accumulator held a safeguard-failure entry (T-INST-116k) or a non-zero-exit entry (T-INST-116j2) — would pass T-INST-116k / T-INST-116j2 and fail this test. The ordinal-window form combined with the FAULT-applied-to-all-workflows pattern makes the test order-independent: whichever workflow is first in the implementation's auto-install order is the one whose spawn fails, and the other two are never reached regardless of which they are. Together with T-INST-116k (post-safeguard-failure-first × safeguard-failure accumulator state) and T-INST-116j2 (post-exit-first × non-zero-npm-exit accumulator state), this closes the no-active-child × signal-termination-suppression contract across all three failure-class accumulator states (safeguard-failure, npm-non-zero-exit, npm-spawn-failure) on the SIGINT axis. *(Spec 10.10, 7.3)*
+- **T-INST-116m2**: SIGTERM delivered **after an `npm install` spawn failure but before the next workflow** (the `post-spawn-failure-first` ordinal window) — SIGTERM-axis parity for T-INST-116m on the spawn-failure-accumulator surface. SPEC 10.10's "Signals during the auto-install pass when no npm child is active" clause names "SIGINT / SIGTERM" together; the no-active-child contract holds for both signals identically, including the aggregate-report-suppression sub-case when the accumulator already holds an `npm-install-spawn-failure` entry. T-INST-116m covers the SIGINT axis on this composed window-and-accumulator state; a buggy implementation that suppressed the aggregate report under SIGINT in the spawn-failure accumulator state but special-cased SIGTERM (e.g., a SIGTERM-handler path that emitted the accumulated report before exiting) would pass T-INST-116m and fail this test. Same fixture, seam configuration, and harness pattern as T-INST-116m: three-workflow source `alpha/`, `beta/`, `gamma/`, each with `index.sh` + a top-level `package.json` and no pre-existing `.gitignore`; `withFakeNpm({ exitCode: 0, logFile })`; `LOOPX_TEST_AUTOINSTALL_FAULT=npm-spawn-fail:alpha,beta,gamma`; `LOOPX_TEST_AUTOINSTALL_PAUSE=post-spawn-failure-first` with `LOOPX_TEST_AUTOINSTALL_PAUSE_MARKER=<absolute-path-to-marker>`; harness polls for the marker, extracts `current` / `processed` / `remaining`, lets `failed = current` and `notReached = remaining`, then sends **SIGTERM** to loopx instead of SIGINT. Assert: (a) loopx exits with code **143** (128 + 15 for SIGTERM — **not** 1, even though `failed`'s spawn failed and an aggregate-report entry was accumulated; the signal supersedes the aggregate-failure exit code per SPEC 10.10's `128 + signal number` clause), (b) the fake-npm shim log records **zero** invocations, (c) `.loopx/<failed>/.gitignore` exists as a regular file containing exactly `node_modules`, (d) for each workflow name `w` in `notReached`, `.loopx/<w>/.gitignore` does **not** exist on disk, (e) `.loopx/alpha/`, `.loopx/beta/`, `.loopx/gamma/` all exist with their committed workflow files byte-for-byte from the source — committed workflow files are **not rolled back**, and (f) **no aggregate failure report** is emitted on stderr — the spawn-failure entry was recorded in the accumulator before the signal arrived, and the signal-termination suppression rule prevents emission for SIGTERM identically to SIGINT. Assertion (f) is the load-bearing one for the parity contract: an implementation whose suppression rule was conditioned on the signal being SIGINT specifically (rather than the SPEC's SIGINT-or-SIGTERM normative pair) would pass T-INST-116m and fail this test. Together with T-INST-116m (SIGINT axis), this closes the SPEC 10.10 SIGINT/SIGTERM parity for the post-spawn-failure-first × spawn-failure-accumulator composed window. *(Spec 10.10, 7.3)*
+
+##### Aggregate-Report-Already-Emitted Carve-out
+
+SPEC 10.10's signal-termination clause has two halves: signal termination **suppresses** the final auto-install aggregate failure report **unless it had already been emitted**. T-INST-116k pins down the **suppression** half (failure recorded, report not yet emitted, signal observed → report suppressed). T-INST-116l covers the complementary **already-emitted carve-out** half via the section 1.4 `LOOPX_TEST_AUTOINSTALL_PAUSE=post-aggregate-report` ordinal value.
+
+- **T-INST-116l**: SIGINT delivered **after the aggregate failure report has been emitted** but before loopx's process exits — the report remains observable on stderr and is not retroactively suppressed by the signal, and committed workflow files plus already-created auto-install side effects remain on disk. SPEC 10.10's "unless it had already been emitted" carve-out plus the SPEC 10.10 / 10.7 / 10.9 no-rollback contract. Multi-workflow source `alpha/`, `beta/`, `gamma/`, each with `index.sh` + a top-level `package.json` and **no** pre-existing `.gitignore`. Use `withFakeNpm({ exitCode: 0, logFile })` and apply `LOOPX_TEST_AUTOINSTALL_FAULT=gitignore-replace-with-fifo:alpha,beta,gamma` so that whichever workflow is processed first has a FIFO at its `.gitignore` immediately before the safeguard `lstat` (causing a safeguard failure that accumulates in the aggregate report). Allocate a harness-controlled marker path under the test's own temp directory (outside `$LOOPX_TMPDIR`). Spawn `loopx install <source>` via `runCLIWithSignal` with `NODE_ENV=test`, `LOOPX_TEST_AUTOINSTALL_PAUSE=post-aggregate-report`, `LOOPX_TEST_AUTOINSTALL_PAUSE_MARKER=<absolute-path>`, and the FAULT seam value. Loopx commits all three workflows, runs the auto-install pass, records the safeguard failure for the first-processed workflow (the other two may also see safeguard failures depending on the implementation's auto-install order, but the seam fires after the first failure is in the accumulator), emits the aggregate failure report to stderr, completes / flushes the stderr write as far as the runtime stream API supports for the underlying handle (stderr is commonly a pipe in tests, where `fsync(2)` is not portable), and pauses for the bounded interval. The seam writes the JSON marker `{"window": "post-aggregate-report", "current": null, "processed": [...], "remaining": []}` per the section 1.4 contract. The harness polls for the marker, captures the loopx-process stderr observed up to that point (so post-pause stderr can be compared), reads the marker's `processed` array (so post-signal disk-state assertions can key off the implementation's actual auto-install order rather than hard-coded names), and sends SIGINT to loopx. After loopx resumes, it exits. Assert: (a) loopx exits with code **130** (128 + 2 for SIGINT — the signal supersedes the aggregate-failure exit code `1` per SPEC 10.10's `128 + signal number` clause), (b) **the aggregate failure report is present on stderr** in the captured output (the report was written before the pause and the signal cannot un-emit it; the post-pause stderr capture must therefore contain the same aggregate report content as a non-signal-terminated baseline run with the same FAULT configuration would — the test compares the report shape per-workflow / per-failure to the baseline), (c) **no second copy of the aggregate report appears in the stderr captured after the signal observation** — the carve-out preserves the already-emitted report, it does not re-emit, (d) **all three committed workflow directories `.loopx/alpha/`, `.loopx/beta/`, `.loopx/gamma/` still exist on disk with their committed workflow files (`index.sh`, `package.json`) byte-for-byte from the source** — the signal arrived after the file-level commit phase and after the aggregate-report-emitting auto-install pass completed, and per SPEC 10.10's "Committed workflow files are not rolled back" / SPEC 10.9's narrowed install-failure-cleanup scope, signal termination at this stage does not roll back the file-level install (parity with the no-rollback contract that the other no-active-child signal tests T-INST-116h / 116i / 116j / 116k assert), and (e) **for each workflow name `w` in the marker's `processed` array, any `.loopx/<w>/.gitignore` FIFO that the FAULT seam materialized before that workflow's safeguard `lstat` is still on disk as a FIFO** (verified via `lstat` returning `S_IFIFO`) — the auto-install side effects already produced before the signal observation are preserved, matching SPEC 10.10's "any `.gitignore` / `node_modules/` side effects completed before the signal observation remain on disk" rule. The (d) and (e) assertions are the no-rollback parity additions: T-INST-116h / 116i / 116j / 116k all assert "committed workflow files still exist with their original content" on the no-active-child signal-window path; this test extends that contract to the post-aggregate-report carve-out window, where a buggy implementation that suppressed only the aggregate-report emission via a "wipe everything we just produced" rollback path on signal would pass (a) / (b) / (c) but fail (d) / (e). Together with T-INST-116k (suppression half) this closes both halves of SPEC 10.10's signal-termination clause for the aggregate-report path, with full no-rollback parity to the suppression-half tests. `@flaky-retry(2)`. *(Spec 10.10, 10.7, 10.9, 7.3)*
+
+##### Signal-Symmetry Parity for No-Active-Child Auto-install Windows
+
+SPEC 10.10's "Signals during the auto-install pass when no npm child is active" clause names "SIGINT / SIGTERM" together — the no-active-child contract holds for both signals identically. T-INST-116h / 116i / 116k / 116l above each cover one of the four no-active-child sub-windows on the SIGINT axis (T-INST-116j is already SIGTERM, T-INST-116j2 is SIGINT after a non-zero npm exit). A window-specific SIGTERM bug — for example, a SIGTERM-handler path different from SIGINT's that fires the safeguard write loop on the next workflow even after a signal observation — could escape coverage when only the SIGINT axis is exercised on these four windows. The following SIGTERM-axis parity tests close that gap, mirroring the existing T-INST-116b2 / T-INST-116d2 SIGTERM-parity pattern for the active-child windows.
+
+- **T-INST-116h2**: SIGTERM delivered **between sequential workflows** (the `between-workflows-after-first` ordinal window) — SIGTERM-axis parity for T-INST-116h. Same fixture, seam configuration, and harness pattern as T-INST-116h, but send **SIGTERM** instead of SIGINT after observing the marker. Assert: (a) loopx exits with code **143** (128 + 15 for SIGTERM), (b)–(f) identical to T-INST-116h's assertions on the auto-install side effects, fake-npm log, committed workflow files, and aggregate-report suppression. A buggy implementation that handled SIGINT correctly on the `between-workflows-after-first` window but continued safeguard writes or npm spawns on SIGTERM (e.g., a SIGTERM-handler path that bypassed the no-active-child preempt branch) would pass T-INST-116h and fail this test. *(Spec 10.10, 7.3)*
+- **T-INST-116i2**: SIGTERM delivered **during `.gitignore` safeguard work before spawning npm** (the `pre-spawn-first` ordinal window) — SIGTERM-axis parity for T-INST-116i. Same fixture, seam configuration, and harness pattern as T-INST-116i — including the pre-signal `lstat`-plus-content snapshot of `.loopx/<first>/.gitignore` taken after polling the marker and before sending the signal — but send **SIGTERM** instead of SIGINT. Assert: (a) loopx exits with code **143**, (b)–(f) identical to T-INST-116i's assertions on the no-spawn outcome, no-write outcome on `untouched` workflows, committed workflow files preserved, aggregate-report suppression, and the conditional snapshot-preservation assertion (f) — if the pre-signal snapshot recorded "exists as a regular file with content C", the post-exit `lstat` returns a regular-file entry and content equals C byte-for-byte; if the snapshot recorded "does not exist", no assertion is made under (f). The pre-spawn-first window's implementation-defined safeguard-write timing (which T-INST-116i leaves open per SPEC 10.10's "If a synchronous or already-started safeguard operation completes before loopx observes the signal, its side effects remain") applies symmetrically here, and the SPEC 10.10 "side effects completed before the signal observation remain on disk" rule that T-INST-116i's (f) pins down on the SIGINT axis must hold identically under SIGTERM — a buggy implementation whose signal-driven cleanup rolled back or mutated the safeguard's pre-pause side effect under SIGTERM but not under SIGINT (or vice versa) would pass T-INST-116i (or this test, respectively) and fail the other. *(Spec 10.10, 7.3)*
+- **T-INST-116k2**: SIGTERM delivered **after a `.gitignore` safeguard failure but before the next workflow** (the `post-safeguard-failure-first` ordinal window) — SIGTERM-axis parity for T-INST-116k. Same fixture (FIFO-replacement FAULT applied to all three workflows), seam configuration, and harness pattern as T-INST-116k, but send **SIGTERM** instead of SIGINT. Assert: (a) loopx exits with code **143**, (b)–(f) identical to T-INST-116k's assertions on the no-spawn outcome, FIFO persistence on `failed`, no-write on `notReached`, committed workflow files preserved, and aggregate-report suppression even when the accumulator already holds a safeguard-failure entry. The load-bearing assertion (f) — aggregate-report suppression on the safeguard-failure accumulator path under SIGTERM — pins the SPEC 10.10 "SIGINT / SIGTERM" parity for the suppression half on this specific accumulator state, which a buggy implementation could plausibly handle correctly under SIGINT but mishandle under SIGTERM via a separate signal-handler dispatch path. *(Spec 10.10, 7.3)*
+- **T-INST-116l2**: SIGTERM delivered **after the aggregate failure report has been emitted** but before loopx's process exits (the `post-aggregate-report` ordinal window) — SIGTERM-axis parity for T-INST-116l. Same fixture, seam configuration, and harness pattern as T-INST-116l, but send **SIGTERM** instead of SIGINT after observing the marker. Assert: (a) loopx exits with code **143**, (b)–(e) identical to T-INST-116l's assertions on the aggregate-report-already-emitted carve-out (report present on stderr; no second copy after the signal; committed workflow files preserved; FIFO side effects preserved). The load-bearing carve-out assertion (b) — already-emitted aggregate report not retroactively suppressed under SIGTERM — pins the SPEC 10.10 carve-out half of "SIGINT / SIGTERM" parity, which a buggy implementation could mishandle under SIGTERM via an over-zealous signal cleanup path that retroactively wiped already-flushed stderr buffers (in environments where stderr is buffered) or retroactively rolled back committed workflow files. `@flaky-retry(2)`. *(Spec 10.10, 10.7, 10.9, 7.3)*
+
+##### No Rollback on Auto-install Failure
+
+- **T-INST-117**: Auto-install failures do not remove committed workflow files. Run T-INST-114 (non-zero exit for `beta/`). After the command exits 1, assert `.loopx/alpha/`, `.loopx/beta/`, and `.loopx/gamma/` all exist on disk with their intended contents (`index.sh`, `package.json`), and any synthesized `.gitignore` files are present. The failure report does not trigger rollback — the user remediates manually. *(Spec 10.10, 10.7, 10.9)*
+- **T-INST-117a**: Partial `node_modules/` state from a failed `npm install` is not cleaned up. Use `withFakeNpm({ createFiles: ["node_modules/partial-file"], exitCode: 1, logFile })`. Run install. After exit 1, assert `.loopx/<name>/node_modules/partial-file` still exists — loopx did not remove it. *(Spec 10.10)*
+- **T-INST-117b**: `loopx install -y <source>` after a prior auto-install failure reinstalls cleanly from scratch — old partial `node_modules/` state is replaced and `npm install` runs again. SPEC 10.10's auto-install failure clause states: "Retries: `loopx install -y <source>` reinstalls from scratch, or `cd .loopx/<workflow> && npm install` retries manually." T-INST-117 / T-INST-117a pin down the *no-rollback* contract on the failure path (committed files and partial `node_modules/` are left intact); T-INST-120 covers the generic `-y` replacement-freshness contract on a manually pre-seeded fixture. Neither directly exercises the explicit **retry sequence** loopx prescribes for remediation: a real auto-install failure followed by `loopx install -y <same-source>`. This test pins down that retry sequence end-to-end so a buggy implementation that skipped re-running `npm install` on `-y` (e.g., by short-circuiting when the workflow directory already exists post-failure) would be caught. **Setup.** Single-workflow source containing `index.sh`, a top-level `package.json`, and **no** `.gitignore` (so the safeguard synthesizes fresh on each pass). **Phase 1 — failed install.** Use `withFakeNpm({ exitCode: 1, createFiles: ["node_modules/partial-file"], logFile: phase1Log })`. Run `loopx install <source>`. Assert: (a1) exit code 1, (b1) `.loopx/ralph/index.sh` and `.loopx/ralph/package.json` exist on disk with their source content (committed despite npm failure — T-INST-117 contract), (c1) `.loopx/ralph/node_modules/partial-file` exists on disk (partial node_modules left intact — T-INST-117a contract), (d1) `.loopx/ralph/.gitignore` exists with `node_modules` content (synthesized before npm spawn), and (e1) the phase-1 fake-npm log records exactly one invocation for `.loopx/ralph/`. **Phase 2 — successful retry.** Replace the fake-npm shim with a fresh `withFakeNpm({ exitCode: 0, logFile: phase2Log })` (no `createFiles` — npm "succeeds" silently in this phase, so the test does not seed a fresh successful `node_modules/` from the shim; the assertions below focus on the **removal of the stale partial state** and the **fresh re-spawn of `npm install`**, not on the post-success contents of `node_modules/`). Run `loopx install -y <same-source>` (same source URL, same destination workflow name). Assert: (a2) exit code 0, (b2) `.loopx/ralph/index.sh` and `.loopx/ralph/package.json` exist with their source content byte-for-byte (replacement committed fresh — `-y` removed the old workflow directory and re-committed from the source), (c2) **`.loopx/ralph/node_modules/partial-file` no longer exists** — the stale partial-`node_modules/` state from phase 1 was removed as part of the `-y` file-level replacement (per SPEC 10.10 "File-level replacement removes the existing workflow directory (including any previously installed `node_modules/` and any previously synthesized `.gitignore`) before the replacement is committed"), (d2) `.loopx/ralph/.gitignore` exists with `node_modules` content — the safeguard ran fresh against the replacement (which has no `.gitignore`), per the standard `-y` × auto-install freshness contract from T-INST-120, and (e2) the phase-2 fake-npm log records exactly one invocation for `.loopx/ralph/` — `npm install` ran again after `-y` re-committed the workflow, even though the same source had been "installed" (with a failed npm) once before. (e2) is the load-bearing assertion: a buggy implementation that treated the workflow as already-present-on-disk and skipped re-spawning `npm install` would pass (a2)/(b2)/(c2)/(d2) (because `-y` correctly removed and replaced the directory) but fail (e2) — because the auto-install pass would not have been re-triggered for the replaced workflow. **Why a separate test (rather than an extension of T-INST-120).** T-INST-120 manually pre-seeds `.loopx/ralph/` with a stale `node_modules/old-marker` to simulate "prior install state" — that pre-seed does not exercise the case where the prior state was created by a real loopx auto-install pass that exited non-zero, which is the explicit scenario named in SPEC 10.10's retry clause. T-INST-117b drives both phases through real `loopx install` invocations against a real fake-npm shim, pinning down the actual retry sequence loopx prescribes rather than a synthetic pre-seed. Together with T-INST-117 / T-INST-117a (no rollback) and T-INST-120 / T-INST-120a / T-INST-120c / T-INST-120d (`-y` replacement freshness across the auto-install-trigger matrix), this test closes the SPEC 10.10 "retry/remediation" path. *(Spec 10.10, 10.5)*
+
+##### Package-Manager Selection (Always `npm`)
+
+SPEC 10.10: "`npm install` unconditionally. loopx does not inspect `bun.lockb`, `pnpm-lock.yaml`, `yarn.lock`, or a `packageManager` field to select a different manager". These tests pin down that loopx never selects a non-npm tool based on lockfile or `packageManager` signals.
+
+All tests use `withFakeNpm({ exitCode: 0, logFile })` and no other shims — so if loopx attempts to spawn `bun`, `pnpm`, or `yarn`, the spawn either finds a real binary on `PATH` (which is unlikely under a test harness with scrubbed `PATH`) or fails, but in either case the `npm` shim log would show zero invocations, failing the assertion.
+
+- **T-INST-118**: `packageManager: "pnpm@..."` field does not cause loopx to select pnpm. Single-workflow source with `package.json` containing `{ "packageManager": "pnpm@8.6.0", "dependencies": {} }` and a sibling `pnpm-lock.yaml`. Use `withFakeNpm`. Run install. Assert: (a) exit code 0, (b) the fake-npm shim log records exactly one invocation for the workflow (cwd = `.loopx/<name>/`, argv = `["install"]`), and (c) no `pnpm` or other manager was spawned (verified via a scrubbed `PATH` that excludes any `pnpm`/`yarn`/`bun` binary — see `T-INST-GLOBAL-01`'s PATH-scrubbing pattern). Per SPEC 10.10 "loopx does not inspect ... a `packageManager` field to select a different manager". *(Spec 10.10)*
+- **T-INST-118a**: `bun.lockb` does not cause loopx to select bun. Single-workflow source with `package.json` and a sibling `bun.lockb` file (a zero-byte placeholder is sufficient for presence detection). Use `withFakeNpm`. Run install. Assert: (a) exit code 0, (b) the fake-npm shim log records exactly one invocation, and (c) no `bun` binary was spawned. *(Spec 10.10)*
+- **T-INST-118b**: `yarn.lock` does not cause loopx to select yarn. Same structure with `yarn.lock` (zero-byte placeholder). Assert the fake-npm shim was invoked; `yarn` was not. *(Spec 10.10)*
+- **T-INST-118c**: Multiple lockfiles and a `packageManager` field still select `npm`. Source with `package.json` containing `{ "packageManager": "yarn@3.6.1" }`, and sibling `bun.lockb`, `pnpm-lock.yaml`, and `yarn.lock` files simultaneously. Use `withFakeNpm`. Assert the fake-npm shim was invoked (exactly once, for the workflow), and no other manager was spawned. Per SPEC 10.10, none of these signals has any effect — `npm install` unconditionally. *(Spec 10.10)*
+
+##### Auto-install Stdout / Stderr Passthrough
+
+SPEC 10.10: "npm's stdout and stderr stream through to loopx's stdout and stderr unchanged; loopx neither buffers nor parses npm output and does not introduce a progress indicator of its own."
+
+- **T-INST-119**: Fake npm's stdout and stderr marker bytes appear unchanged in loopx's stdout / stderr, and loopx adds no progress indicator of its own. Single-workflow source with a top-level `package.json` (and `index.sh`, `.gitignore` absent so the safeguard synthesizes silently — see (d) below). Use `withFakeNpm({ exitCode: 0, stdout: "npm-stdout-MARKER\n", stderr: "npm-stderr-MARKER\n", logFile })`. Run `loopx install <source>`. Capture loopx's stdout and stderr. Assert: (a) exit code 0, (b) loopx's stdout contains the marker `"npm-stdout-MARKER"` as an **exact standalone line** — i.e., the byte sequence `"npm-stdout-MARKER\n"` appears with its **leading boundary** at the start of the stdout stream or immediately after a `\n` and its trailing `\n` intact (matchable as the regex `/(^|\n)npm-stdout-MARKER\n/`), and loopx's stderr likewise contains `"npm-stderr-MARKER"` as an exact standalone line (matchable as `/(^|\n)npm-stderr-MARKER\n/`) — per SPEC 10.10 "npm's stdout and stderr stream through to loopx's stdout and stderr unchanged". The exact-standalone-line bound is stricter than a plain substring match: a buggy implementation that prefixed npm lines (e.g., emitting `[npm] npm-stdout-MARKER\n` or `loopx: npm-stdout-MARKER\n`) would still contain the substring `"npm-stdout-MARKER"` but would fail the exact-line check because the marker would not be at a line-start boundary. The check still admits SPEC-defined auxiliary loopx output **on separate lines** before or after the npm bytes (consistent with the scope note below); (c) loopx's stdout / stderr contain **no progress indicator** — narrowly scoped to spinner / progress-bar / progress-percentage output (any common spinner glyph such as `⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏`; any percentage-progress pattern like `%`-suffixed numerics on a stand-alone line; any progress-bar glyph sequence like `[####    ]`). The check is defense-in-depth against the SPEC 10.10 "does not introduce a progress indicator of its own" clause. **The check does not forbid all loopx-emitted output around the npm bytes.** SPEC 10.10 only forbids a "progress indicator"; it does not forbid SPEC-defined auxiliary success output (e.g., a future SPEC-defined per-workflow status line or summary), and it does not forbid plain status / log lines that are not themselves progress indicators (e.g., a hypothetical "Running npm install…" or "Installing dependencies…"-style line is *not* a progress indicator under SPEC 10.10's narrow reading and is therefore not asserted against by this test). The (c) assertion is therefore narrowed to actual progress-indicator output — spinners, progress bars, and progress percentages — and not to "what loopx is doing right now" status lines that fall outside SPEC 10.10's progress-indicator clause; and (d) the fake-npm shim log records exactly one invocation for `.loopx/<workflow>/` (proving the npm child actually ran), so the marker assertions in (b) are anchored on a real spawn rather than a no-op. **Scope note.** This test does **not** require loopx's full stdout / stderr to equal the npm bytes — SPEC 10.10 only requires the npm child's bytes to stream through unchanged. Asserting whole-stream equality would over-pin behavior beyond SPEC, because loopx is permitted to emit auxiliary output that is *separately specified by SPEC* — `-y` replacement-stale-state messages (T-INST-120), malformed-`package.json` warnings from SPEC 3.2 (T-INST-113), `.gitignore` write-failure stderr (T-INST-112c), and aggregate failure reports (T-INST-114). Those SPEC-defined aggregate reports / warnings are permitted alongside npm bytes. The marker-byte-substring assertion in (b) plus the narrowed no-progress-indicator assertion in (c) together capture the SPEC 10.10 contract scoped to what SPEC explicitly bans (progress indicator) without forbidding SPEC-defined non-progress success output or plain status lines. **Stricter-rule pathway.** If a future ADR-0004-scoped review concludes that *all* loopx-authored status lines around npm output should be banned (i.e., that "does not introduce a progress indicator of its own" should be read as "loopx emits no additional status / progress output of its own around npm output"), the resolution path is to add an ADR-0004-scoped `SPEC-PROBLEMS.md` entry first, clarify SPEC 10.10's text accordingly, and then extend (c) to forbid the additional status-line forms — not to add the stricter assertion to this test ahead of the SPEC clarification. Tests covering the SPEC-defined auxiliary-output paths (T-INST-113 / 112c / 114 / 120) exercise their respective non-success-path conditions; this test pins down the success-path npm-passthrough and progress-indicator-absence contract. T-INST-119a covers the "stream through" / "neither buffers" timing axis that this test does not exercise. *(Spec 10.10)*
+- **T-INST-119a**: Fake npm bytes stream through loopx in real time (no buffering until child exit). SPEC 10.10 says "loopx neither buffers nor parses npm output" — the "neither buffers" half is observable only by watching for npm's bytes **before** the npm child has exited; final-output capture (as in T-INST-119) cannot distinguish "streamed promptly" from "buffered until exit." This requires the harness to observe loopx's stdout incrementally; it is the stdout counterpart to `runCLIWithSignal`'s existing `waitForStderr` and presumes the harness exposes a parallel `waitForStdout(pattern, options?)` method on `CLIProcessHandle`. Single-workflow source with a top-level `package.json`. Use `withFakeNpm({ exitCode: 0, stdout: "npm-streaming-MARKER\n", sleepSeconds: 5, pidFile, logFile })` — the shim writes its PID to `pidFile`, writes the marker line to **stdout** (not just stderr), then sleeps 5 seconds, then exits 0. The `pidFile` exposes the shim's PID while it is still alive (per the helper contract — the per-invocation log entry is finalized at exit and is therefore not usable here). Run `loopx install <source>` via `runCLIWithSignal`. Within a tight timeout (e.g., 2 seconds — well under the shim's 5-second sleep), call `await handle.waitForStdout(/(^|\n)npm-streaming-MARKER\n/)` to observe the marker as an **exact standalone line** on loopx's stdout **before the npm child has exited**. The exact-line regex (rather than a plain `"npm-streaming-MARKER"` substring) is stricter: a buggy implementation that streamed npm bytes promptly but prefixed each line (e.g., `[npm] npm-streaming-MARKER\n`) would still satisfy a substring match but would fail the line-boundary check because the marker would not be at a line-start boundary. Assert: (a) `waitForStdout(/(^|\n)npm-streaming-MARKER\n/)` resolves within the pre-exit window (i.e., before the shim's 5-second sleep would have ended), (b) at the time the marker is observed, the shim PID (read from `pidFile`) is still alive (verified via `kill -0 <shim-pid>` returning success — `kill -0` does not send a signal but checks process existence; an implementation that buffered npm's stdout until child exit would fail this check because the marker would not be observable until after the shim exits), then await `handle.waitForExit()` and (c) the final exit code is 0. The shim's 5-second sleep gives loopx ample time to flush its buffer; a buffering implementation would not flush until the child closed its stdout (after the sleep), so the 2-second `waitForStdout` would time out. T-INST-119 covers "bytes appear unchanged in final captured output"; this test covers "bytes appear in real time." Together they pin down both halves of SPEC 10.10's stream-through contract. **Implementer note for the harness.** This test requires `runCLIWithSignal` (section 2.3) to expose a `waitForStdout(pattern: string | RegExp, options?: { timeoutMs?: number }): Promise<void>` method on `CLIProcessHandle`, parallel to the existing `waitForStderr`. *(Spec 10.10)*
+- **T-INST-119a-stderr**: Fake npm bytes stream through loopx's **stderr** in real time (no buffering until child exit). Companion to T-INST-119a, which covers the real-time-streaming axis on **stdout** only. SPEC 10.10 specifies the real-time / no-buffering contract for both streams: "npm's stdout and stderr stream through to loopx's stdout and stderr unchanged; loopx neither buffers nor parses npm output." The "neither buffers" half applies symmetrically to **stderr** as well as stdout — and the timing-axis observation requires watching the bytes appear before the child exits, which T-INST-119 (final-output capture) cannot distinguish from "buffered until exit." T-INST-119a uses `waitForStdout` to pin down the stdout half; this test pins down the stderr half via `waitForStderr`, which is already part of `runCLIWithSignal`'s `CLIProcessHandle` (section 2.3). Single-workflow source with a top-level `package.json`. Use `withFakeNpm({ exitCode: 0, stderr: "npm-streaming-stderr-MARKER\n", sleepSeconds: 5, pidFile, logFile })` — the shim writes its PID to `pidFile`, writes the marker line to **stderr** (not stdout), then sleeps 5 seconds, then exits 0. The `pidFile` exposes the shim's PID while it is still alive (per the helper contract — the per-invocation log entry is finalized at exit and is therefore not usable here). Run `loopx install <source>` via `runCLIWithSignal`. Within a tight timeout (e.g., 2 seconds — well under the shim's 5-second sleep), call `await handle.waitForStderr(/(^|\n)npm-streaming-stderr-MARKER\n/)` to observe the marker as an **exact standalone line** on loopx's stderr **before the npm child has exited**. The exact-line regex (rather than a plain `"npm-streaming-stderr-MARKER"` substring) is stricter: a buggy implementation that streamed npm stderr bytes promptly but prefixed each line (e.g., `[npm] npm-streaming-stderr-MARKER\n`) would still satisfy a substring match but would fail the line-boundary check. Assert: (a) `waitForStderr(/(^|\n)npm-streaming-stderr-MARKER\n/)` resolves within the pre-exit window (i.e., before the shim's 5-second sleep would have ended), (b) at the time the marker is observed, the shim PID (read from `pidFile`) is still alive (verified via `kill -0 <shim-pid>` returning success — `kill -0` does not send a signal but checks process existence; an implementation that buffered npm's stderr until child exit would fail this check because the marker would not be observable until after the shim exits), then await `handle.waitForExit()` and (c) the final exit code is 0. The shim's 5-second sleep gives loopx ample time to flush its stderr buffer; a buffering implementation would not flush until the child closed its stderr stream (after the sleep), so the 2-second `waitForStderr` would time out. Together with T-INST-119 (final-bytes-unchanged on both streams) and T-INST-119a (real-time stdout streaming), this test pins down the full "stream through" / "neither buffers" SPEC 10.10 contract symmetrically across stdout and stderr — a buggy implementation that streamed stdout in real time but buffered stderr (or vice versa) would pass T-INST-119 / T-INST-119a but fail this test. *(Spec 10.10)*
+- **T-INST-119b**: Fake npm's stdout and stderr marker bytes appear unchanged in loopx's stdout / stderr **on the non-zero-exit failure path**. SPEC 10.10's stream-through contract ("npm's stdout and stderr stream through to loopx's stdout and stderr unchanged") does not branch on the npm child's exit status — passthrough applies regardless of whether `npm install` succeeds or fails. T-INST-119 / T-INST-119a cover the success path (`exitCode: 0`); this test pins down the failure path so a buggy implementation that suppressed or rewrote npm's output when npm exited non-zero (e.g., to surface its own aggregate failure report and hide the "noisy" npm bytes) would be caught. Single-workflow source with `index.sh` and a top-level `package.json`. Use `withFakeNpm({ exitCode: 1, stdout: "npm-fail-stdout-MARKER\n", stderr: "npm-fail-stderr-MARKER\n", logFile })` — the shim writes the marker lines to stdout and stderr, then exits non-zero. Run `loopx install <source>`. Capture loopx's stdout and stderr. Assert: (a) exit code 1 — the npm non-zero exit causes the install to fail per SPEC 10.10's "non-zero exit" branch (paired with T-INST-114's aggregate-report behavior), (b) loopx's stdout contains the marker `"npm-fail-stdout-MARKER"` as an **exact standalone line** — the byte sequence `"npm-fail-stdout-MARKER\n"` appears with its leading boundary at the start of the stdout stream or immediately after a `\n` and its trailing `\n` intact (matchable as `/(^|\n)npm-fail-stdout-MARKER\n/`) — the npm stdout marker survived the failure path, (c) loopx's stderr contains `"npm-fail-stderr-MARKER"` as an exact standalone line (matchable as `/(^|\n)npm-fail-stderr-MARKER\n/`) — the npm stderr marker also survived, and (d) the fake-npm shim log records exactly one invocation, anchoring the marker assertions on a real spawn rather than a no-op. The exact-line bound (rather than a plain substring match) is stricter on the failure path for the same reason as T-INST-119: a buggy implementation that wrapped npm output by prefixing each line (e.g., `[npm] npm-fail-stdout-MARKER\n`) would still contain the marker substring but fail the line-boundary check, distinguishing genuine byte-for-byte failure-path passthrough from a substring-only match. Auxiliary stderr from the aggregate failure report is permitted on its own line(s) before or after the npm marker. **Scope note.** As with T-INST-119, this test does **not** require loopx's full stdout / stderr to equal the npm bytes — it only requires the npm child's bytes to stream through unchanged on the failure path. Auxiliary stderr bytes like an aggregate failure report (e.g., "Workflow `<name>` failed: npm install exited 1") are permitted alongside the npm marker, since SPEC 10.10 explicitly defines the aggregate-report behavior on non-zero npm exits. T-INST-114 covers the aggregate report contract; this test covers the byte-passthrough contract on the same failure terminal. A buggy implementation that buffered npm output and discarded it on non-zero exit (replacing it with the aggregate-report-only stderr) would pass T-INST-114 but fail (c); an implementation that streamed npm bytes only on success would pass T-INST-119 / T-INST-119a but fail this test. *(Spec 10.10)*
+
+##### `-y` Replacement: Auto-install Freshness
+
+SPEC 10.10 "Interaction with `-y`": "File-level replacement removes the existing workflow directory (including any previously installed `node_modules/` and any previously synthesized `.gitignore`) before the replacement is committed; the safeguard and `npm install` then run fresh against the replacement's `package.json` and `.gitignore` (or absence thereof)."
+
+- **T-INST-120**: `-y` replacement removes old `node_modules/` and synthesized `.gitignore`, then auto-install runs fresh. Pre-seed `.loopx/ralph/` (before running the install command under test) with `ralph/index.sh`, `ralph/package.json`, `ralph/node_modules/old-marker` (a file whose continued presence proves stale `node_modules/` was not cleaned), and a previously synthesized `ralph/.gitignore` containing exactly `node_modules\n`. Prepare a **replacement** single-workflow source with `index.sh` and `package.json` but **no** `.gitignore` and **no** `node_modules/`. Use `withFakeNpm({ exitCode: 0, logFile })`. Run `loopx install -y <replacement-source>`. Assert: (a) exit code 0, (b) `.loopx/ralph/node_modules/old-marker` does **not** exist after the command completes — the old `node_modules/` was removed as part of replacement, (c) a fresh `.loopx/ralph/.gitignore` exists containing exactly `node_modules` (optionally with a single trailing newline — implementation-defined) — the safeguard was re-synthesized fresh against the replacement (which had no `.gitignore`), and (d) the fake-npm shim log records exactly one invocation for `.loopx/ralph/` — `npm install` ran fresh against the replacement. (Informational stderr about removing the stale `node_modules/` or prior synthesized `.gitignore` is permitted — SPEC 10.10 only requires replacement to run fresh, not to be silent.) *(Spec 10.10, 10.5)*
+- **T-INST-120a**: `-y` replacement preserves a pre-existing `.gitignore` in the **replacement** source. Pre-seed `.loopx/ralph/` with `node_modules/old-marker` and a previously-synthesized `.gitignore` (containing `node_modules\n`) as in T-INST-120. Prepare a replacement source with `index.sh`, `package.json`, and a `.gitignore` containing `dist/\n# custom\n` (pre-existing). Use `withFakeNpm`. Run `loopx install -y <replacement-source>`. Assert: (a) exit code 0, (b) old `node_modules/` is gone, (c) the installed `.loopx/ralph/.gitignore` has the replacement's content (`dist/\n# custom\n`) — the replacement's pre-existing `.gitignore` is **not** overwritten by loopx's safeguard (T-INST-112a behavior applies fresh), (d) the fake-npm shim ran once for `.loopx/ralph/`. *(Spec 10.10, 10.5)*
+- **T-INST-120b**: Auto-install still runs when `-y` overrides a workflow version mismatch. Single-workflow source with `index.sh` and a top-level `package.json` that (a) declares a `loopx` version range not satisfied by the running version (e.g., `{ "dependencies": { "loopx": ">=999.0.0" } }`) and (b) therefore would ordinarily block install at preflight. Use `withFakeNpm({ exitCode: 0, logFile })`. Run `loopx install -y <source>` (no pre-existing `.loopx/<name>/` destination). Assert: (a) exit code 0 — `-y` suppressed the preflight version-mismatch error (SPEC 10.6), (b) the workflow is committed at `.loopx/<name>/` with `index.sh` and its `package.json` (version declaration preserved), (c) the fake-npm shim log records **exactly one** invocation for the workflow (auto-install ran after `-y` suppressed the preflight failure — SPEC 10.10 "auto-install fires on every committed workflow with a top-level `package.json`" is unaffected by how the commit was unlocked), and (d) `.gitignore` safeguard was synthesized. Existing tests cover `-y` overriding version mismatch (T-INST-72–76 / T-INST-60i / T-INST-60j) and auto-install separately, but none pins down that the combination still produces a commit *and* a fresh auto-install pass. An implementation that gated auto-install on "preflight did not report a version mismatch" — rather than on "the commit succeeded for this workflow" — would fail this test. *(Spec 10.10, 10.6)*
+- **T-INST-120c**: `-y` replacement where the **replacement source has no `package.json`** removes old workflow contents (including any stale `node_modules/` and previously synthesized `.gitignore`) and skips auto-install entirely. SPEC 10.10 "Interaction with `-y`": "File-level replacement removes the existing workflow directory ... before the replacement is committed; the safeguard and `npm install` then run fresh against the replacement's `package.json` and `.gitignore` (or absence thereof)." When the replacement has **no** `package.json`, the auto-install trigger condition (top-level `package.json` present) fails, so no `npm install` runs and no `.gitignore` is synthesized — closing a useful `-y` × auto-install trigger boundary. T-INST-120 covers `-y` replacement when both pre-existing and replacement have `package.json`; T-INST-120a covers `-y` replacement preserving a pre-existing `.gitignore` in the replacement; this test pins down the **replacement-without-`package.json`** branch, where the post-commit auto-install pass must skip the workflow silently. **Pre-seed** `.loopx/ralph/` (before running the install command under test) with `ralph/index.sh`, `ralph/package.json` (any valid loopx range or no loopx declaration — content is irrelevant since this workflow is being replaced), `ralph/node_modules/old-marker` (a file whose continued presence would prove stale `node_modules/` was not cleaned), and a previously synthesized `ralph/.gitignore` containing exactly `node_modules\n`. Prepare a **replacement** single-workflow source with `index.sh` (and optionally additional script files) but **no** top-level `package.json` and **no** `node_modules/` and **no** `.gitignore`. Use `withFakeNpm({ exitCode: 0, logFile })` so the test can observe whether `npm install` was invoked. Run `loopx install -y <replacement-source>`. Assert: (a) exit code 0, (b) `.loopx/ralph/node_modules/old-marker` does **not** exist after the command completes — the old `node_modules/` was removed as part of file-level replacement (the same as T-INST-120's stale-`node_modules/`-removal contract), (c) `.loopx/ralph/package.json` does **not** exist — the replacement source had none, and the `-y` replacement removed the pre-existing one along with the rest of the old workflow directory, (d) `.loopx/ralph/.gitignore` does **not** exist — the replacement had no `.gitignore`, the previously synthesized one was removed with the old workflow directory, and the auto-install safeguard does not synthesize a new one because the trigger condition (top-level `package.json` present) failed, (e) the **fake-npm shim log records zero invocations** — `npm install` did not run because the replacement had no `package.json`, matching SPEC 10.10's "Workflows without a top-level `package.json` are skipped silently — no warning, no npm invocation", and (f) the replacement's workflow files (e.g., `index.sh`) are present at `.loopx/ralph/`, proving the file-level replacement and commit phases ran successfully even though auto-install was skipped. (Informational stderr about removing the stale `node_modules/`, prior `package.json`, or prior synthesized `.gitignore` is permitted but not required — SPEC 10.10 only requires replacement to run fresh, not to be silent or noisy on those state changes.) Together with T-INST-120 (replacement with `package.json`) and T-INST-120a (replacement with pre-existing `.gitignore`), this completes the `-y` × auto-install-trigger-boundary coverage across the {pre-existing has `package.json`} × {replacement has / does not have `package.json`} matrix. *(Spec 10.10, 10.5)*
+- **T-INST-120d**: `-y --no-install` replacement removes old workflow contents (including stale `node_modules/` and previously synthesized `.gitignore`) and skips both `npm install` **and** `.gitignore` synthesis. SPEC 10.10 "Interaction with `-y`" combined with the `--no-install` opt-out: file-level replacement happens normally (the old workflow directory is removed and the replacement is committed), but the `--no-install` flag suppresses the post-commit auto-install pass entirely — meaning no `npm install` runs and no `.gitignore` is synthesized for the replacement workflow (per SPEC 10.10 "`.gitignore` synthesis is skipped under the same conditions that skip `npm install` (`--no-install`, missing top-level `package.json`, malformed `package.json`)"). T-INST-120 covers `-y` replacement triggering a fresh auto-install; T-INST-120a covers `-y` replacement preserving a pre-existing `.gitignore` in the replacement (still under auto-install); T-INST-120c covers `-y` replacement where the replacement has no `package.json` (auto-install skipped because the trigger fails). This test covers the **explicit-opt-out** branch where the replacement *would* have triggered auto-install (it has `package.json`) but `--no-install` suppresses it, pinning down the SPEC 10.10 `-y` × `--no-install` interaction directly. **Pre-seed** `.loopx/ralph/` (before running the install command under test) with `ralph/index.sh`, `ralph/package.json` (any valid loopx range — content irrelevant since this workflow is being replaced), `ralph/node_modules/old-marker` (a file whose continued presence would prove stale `node_modules/` was not cleaned), and a previously synthesized `ralph/.gitignore` containing exactly `node_modules\n`. Prepare a **replacement** single-workflow source with `index.sh` and a top-level `package.json` (so auto-install would normally fire) but **no** `.gitignore` (so a buggy implementation that ignored `--no-install` and synthesized a fresh `.gitignore` would be observable) and **no** `node_modules/`. Use `withFakeNpm({ exitCode: 0, logFile })` so the test can observe whether `npm install` was invoked. Run `loopx install -y --no-install <replacement-source>`. Assert: (a) exit code 0, (b) `.loopx/ralph/node_modules/old-marker` does **not** exist after the command completes — the old `node_modules/` was removed as part of file-level replacement (the `-y` removal happens regardless of `--no-install`, since `--no-install` only suppresses the post-commit auto-install pass — not the pre-commit removal), (c) the **fake-npm shim log records zero invocations** — `--no-install` suppressed the auto-install pass, so `npm install` did not run for the replacement workflow, (d) `.loopx/ralph/.gitignore` does **not** exist — the replacement had no `.gitignore`, the previously synthesized one was removed with the old workflow directory, and the safeguard did not synthesize a new one because `--no-install` suppressed the safeguard step (per SPEC 10.10's "skipped under the same conditions that skip `npm install`"), (e) the replacement's workflow files (`index.sh`, `package.json`) are present at `.loopx/ralph/` byte-for-byte from the source, proving the file-level replacement and commit phases ran successfully, and (f) `.loopx/ralph/node_modules/` does **not** exist (no fresh `node_modules/` was populated; the old one was removed in (b) and `--no-install` skipped re-population). A buggy implementation that treated `--no-install` as gating only the npm-spawn step but left `.gitignore` synthesis intact would fail (d); an implementation that special-cased `-y` to always fire the safeguard regardless of `--no-install` would also fail (d); an implementation that fired `npm install` despite the explicit opt-out would fail (c). Together with T-INST-120 (`-y` triggers auto-install fresh), T-INST-120a (`-y` preserves pre-existing `.gitignore` under auto-install), and T-INST-120c (`-y` with replacement-without-`package.json` skips auto-install via the trigger-condition path), this completes the `-y` × auto-install-suppression-axis coverage across the explicit-opt-out branch — distinct from T-INST-120c's trigger-condition-failure branch. *(Spec 10.10, 10.5)*
+
 #### Global Install Smoke Test
 
-- **T-INST-GLOBAL-01**: Full global install lifecycle, including workflow-side `import "loopx"` resolution. `npm pack` the built loopx package, install the resulting tarball into an isolated global prefix, and create a fixture project with a `.loopx/ralph/index.ts` script whose content is `import { output } from "loopx"; output({ stop: true });`. Run `<tempdir>/bin/loopx run ralph` (no `-n`) against the fixture project. Assert: (a) exit code 0 (the loop halted cleanly via `stop: true`, proving the import resolved and `output()` executed), and (b) the script actually ran (e.g., marker file written before the `output()` call, or infer from the clean `stop: true` exit). The fixture must exercise `import "loopx"` — just asserting "a TS workflow runs globally" is too weak for Spec 3.1 under the workflow model; this proves a global install is sufficient for workflow JS/TS scripts that import loopx helpers. The spawn environment **must not leak dev-tree binaries into the installed loopx**: PATH must be constructed to include only the isolated global prefix's `bin/` and a minimal system PATH (e.g., `/usr/bin`, `/usr/local/bin`, and whatever directory provides the Node/Bun interpreter under test), with all ancestor `node_modules/.bin` entries filtered out — passing `process.env.PATH` through unchanged is forbidden, because `npm run`/`npx` prepend the loopx repo's `./node_modules/.bin` before invoking vitest, which would silently supply `tsx`, `bun`, and any other binary the runner spawns from the dev tree and mask a missing declared dependency in the published package. The child process's cwd must likewise sit outside the loopx repo so that no ancestor-walked `node_modules/` can resolve transpilers or other runtime binaries. The test must also guard against symlink-based leakage (e.g., `npm install -g .` from a local path creating a symlink back into the dev `dist/`): install from the packed tarball, not a directory, and assert that the installed `loop-extender` package root is a real directory, not a symlink, before running the fixture. *(Spec 3.1, 3.3)*
-- **T-INST-GLOBAL-01a**: `[Bun]` Full global install lifecycle under Bun. Same fixture, spawn-environment requirements (scrubbed PATH with no dev-tree `node_modules/.bin`, cwd outside the loopx repo, real-directory install from packed tarball), and assertions as T-INST-GLOBAL-01 (workflow `index.ts` uses `import { output } from "loopx"; output({ stop: true });`), but run via Bun. Proves global install plus workflow-side `import "loopx"` resolution both work under Bun. *(Spec 3.1, 3.3)*
+- **T-INST-GLOBAL-01**: Full global install lifecycle, including workflow-side `import { input, output } from "loopx"` resolution for **both** helpers. `npm pack` the built loopx package, install the resulting tarball into an isolated global prefix, and create a fixture project with a `.loopx/ralph/index.ts` script whose content imports **both** named helpers from `"loopx"`: `import { input, output } from "loopx"; const piped = await input(); output({ result: piped === "" ? "no-input" : piped, stop: true });`. The first iteration's `input()` resolves to an **empty string** `""` (no piped input on first iteration per SPEC 6.5 / 6.7 — `input()` returns a `Promise<string>` and resolves to `""` on the first iteration, never `null` or `undefined`), so the `piped === ""` branch fires and the script outputs `{ result: "no-input", stop: true }`. **Do not use `piped ?? "no-input"`** — since `input()` resolves to `""` (not `null` / `undefined`), the nullish-coalescing operator would leave `piped` as the empty string, the ternary would return `""`, and the fixture's `{ result: "" }` output would pass a stop-based exit-code check regardless of whether `input()` actually executed; worse, a buggy implementation whose `input()` returned `undefined` would also be silently accepted. The explicit `piped === ""` comparison asserts the SPEC-specified first-iteration return value, distinguishing "`input()` resolved correctly to `\"\"`" from "`input()` returned `undefined` (broken shape)". As a defense-in-depth step, a separate marker file also records the JS-level type of `piped` (e.g., `typeof piped` and its length) before the `output()` call so the assertion can confirm the SPEC-specified `string` type. Run `<tempdir>/bin/loopx run ralph` (no `-n`) against the fixture project. Assert: (a) exit code 0 (the loop halted cleanly via `stop: true`, proving **both** imports resolved and `input()` + `output()` both executed), and (b) the script actually ran and observed `piped === ""` (verified via the marker file recording `typeof piped === "string"` and `piped.length === 0`). The fixture must exercise `import "loopx"` for both helpers — SPEC 3.1 explicitly says "A global install is sufficient for all loopx functionality, including JS/TS scripts that `import { output, input } from \"loopx\"`", so a fixture importing only one of the two would not fully exercise that contract. A buggy implementation that exported `output` from the global install but not `input` (or vice versa) would pass an `output`-only fixture but fail this test on the missing-`input` import. The spawn environment **must not leak dev-tree binaries into the installed loopx**: PATH must be constructed to include only the isolated global prefix's `bin/` and a minimal system PATH (e.g., `/usr/bin`, `/usr/local/bin`, and whatever directory provides the Node/Bun interpreter under test), with all ancestor `node_modules/.bin` entries filtered out — passing `process.env.PATH` through unchanged is forbidden, because `npm run`/`npx` prepend the loopx repo's `./node_modules/.bin` before invoking vitest, which would silently supply `tsx`, `bun`, and any other binary the runner spawns from the dev tree and mask a missing declared dependency in the published package. The child process's cwd must likewise sit outside the loopx repo so that no ancestor-walked `node_modules/` can resolve transpilers or other runtime binaries. The test must also guard against symlink-based leakage (e.g., `npm install -g .` from a local path creating a symlink back into the dev `dist/`): install from the packed tarball, not a directory, and assert that the installed `loopx` package root is a real directory, not a symlink, before running the fixture. *(Spec 3.1, 3.3, 6.5, 6.7)*
+- **T-INST-GLOBAL-01a**: `[Bun]` Full global install lifecycle under Bun. Same fixture (workflow `index.ts` uses `import { input, output } from "loopx"; const piped = await input(); output({ result: piped === "" ? "no-input" : piped, stop: true });` — exercising **both** helpers per SPEC 3.1, and using the explicit `piped === ""` comparison rather than `piped ?? "no-input"` because SPEC 6.5 / 6.7 specify that first-iteration `input()` resolves to `""`, not `null` / `undefined`, so a nullish-coalescing fallback would silently mask a broken `input()` shape), the same `typeof piped === "string"` / `piped.length === 0` marker-file check, same spawn-environment requirements (scrubbed PATH with no dev-tree `node_modules/.bin`, cwd outside the loopx repo, real-directory install from packed tarball), and assertions as T-INST-GLOBAL-01, but run via Bun. Proves global install plus workflow-side `import { input, output } from "loopx"` resolution for both helpers works under Bun. *(Spec 3.1, 3.3, 6.5, 6.7)*
 
 ### 4.11 Signal Handling
 
@@ -1565,11 +3194,53 @@ Signal tests use the `signal-ready-then-sleep`, `signal-trap-exit`, `signal-trap
 - **T-SIG-02**: Send SIGTERM to loopx while a script is running. Assert exit code 143. *(Spec 7.3)*
 - **T-SIG-03**: After SIGINT, the child script process is no longer running. *(Spec 7.3)*
 - **T-SIG-04**: Grace period: child traps SIGTERM and exits within 2 seconds → no SIGKILL needed. *(Spec 7.3)*
+- **T-SIG-04a**: SIGINT grace-period parity. SPEC 7.3 names "SIGINT / SIGTERM" together as the signals subject to the active-child grace-period rule, but T-SIG-04 covers SIGTERM only. SIGINT counterpart: child traps SIGINT (handler sleeps briefly then exits 0) and exits within 2 seconds → no SIGKILL needed. Use a `signal-trap-exit` fixture variant that traps SIGINT (instead of SIGTERM); deliver SIGINT to loopx via `runCLIWithSignal`. Assert: (a) loopx exits 130 (128 + 2 for SIGINT), (b) the child's PID (captured from the marker) no longer appears in the process table, and (c) the test completes within ~3 seconds (well under the 5-second grace period — proving SIGKILL escalation did not fire because the child exited cleanly within grace). A buggy implementation that special-cased grace-period handling to SIGTERM only (e.g., immediately killing on SIGINT without grace) would fail this test. *(Spec 7.3)*
 - **T-SIG-05**: Grace period exceeded: child traps SIGTERM and hangs → SIGKILL after ~5 seconds. *(Spec 7.3)*
+- **T-SIG-05a**: SIGINT escalation parity. SIGINT counterpart to T-SIG-05 — proves the 5-second grace + SIGKILL escalation rule is signal-agnostic across SIGINT / SIGTERM per SPEC 7.3. Use a `signal-trap-ignore` fixture variant that traps **SIGINT** (`trap '' INT`) and ignores it, then sleeps indefinitely. Deliver SIGINT to loopx via `runCLIWithSignal`. Assert: (a) loopx waits approximately 5 seconds before the child is terminated (tolerance window 4–7 s, matching T-SIG-05), (b) loopx exits with code 130 (128 + 2 for SIGINT — the originally-forwarded signal, not the SIGKILL escalation), (c) the child PID no longer appears in the process table (SIGKILL took effect because the child trapped/ignored SIGINT). `@flaky-retry(2)` due to the real-time 5-second wait, matching T-SIG-05's tolerance. A buggy implementation that escalated to SIGKILL only for SIGTERM-trapping children — short-circuiting the grace period for SIGINT — would fail this test. *(Spec 7.3)*
 - **T-SIG-06**: Process group signal: script spawns a grandchild. Both terminated after SIGTERM. *(Spec 7.3)*
+- **T-SIG-06a**: SIGINT process-group parity. SIGINT counterpart to T-SIG-06 — proves SPEC 7.3's "The signal is forwarded to the **active child process group**" rule fires for SIGINT, not just SIGTERM. Use the `spawn-grandchild` fixture (which is already signal-agnostic — it spawns a long-lived background subprocess and waits, regardless of which signal terminates the script). Deliver SIGINT to loopx via `runCLIWithSignal`. Assert: (a) loopx exits 130 (128 + 2 for SIGINT), (b) the script's PID and the grandchild PID (both captured from the marker file before signaling) no longer appear in the process table — SIGINT was forwarded to the entire process group, terminating the grandchild as well. A buggy implementation that forwarded SIGINT only to the direct child (not the process group) would leave the grandchild orphaned and fail this test, while passing T-SIG-06 (which only exercises SIGTERM). *(Spec 7.3)*
 - **T-SIG-07**: Between-iterations signal. Assert loopx exits immediately. `@flaky-retry(3)`. *(Spec 7.3)*
+- **T-SIG-07a**: Between-iterations signal also runs `LOOPX_TMPDIR` cleanup. SPEC 7.3 / 7.4 specify that when `LOOPX_TMPDIR` has been created, cleanup runs before loopx exits with the signal's code — and "When no child is active, cleanup runs immediately." T-SIG-07 covers the immediate-exit contract for the between-iterations window; this test pins down the tmpdir-cleanup contract on the same window. Set up `.loopx/ralph/index.sh` that, on its first iteration, (1) observes `LOOPX_TMPDIR` into a marker file, (2) writes its own PID to a separate marker file via `printf '%s' "$$" > <pidMarker>`, (3) writes `"ready-iter-N"` to stderr (where N is the 1-based iteration index, derived from a counter file the script maintains under `$LOOPX_TMPDIR`), then emits a `goto:"ralph:index"` to advance the loop — and on iteration 2 onward, **sleeps indefinitely** before writing any ready marker, so that the between-iterations window between iteration 1 exiting and iteration 2's sleep starting is the only window where the harness can deliver a signal. Run via `runCLIWithSignal` with `-n 5`. Harness: read `LOOPX_TMPDIR` and the iteration-1 child PID from the two markers after `waitForStderr("ready-iter-1")`, then **poll `kill(pid1, 0)` until it returns ESRCH** (iteration 1's child process has exited — confirming loopx is now in the between-iterations window, parsing output and preparing the next spawn), and **only then** deliver SIGINT to loopx. Because iteration 2's script sleeps indefinitely before emitting any ready marker, any signal delivered after `kill(pid1, 0)` returns ESRCH but before iteration 2's shell has begun is delivered in the between-iterations window (no child is active). A narrow residual race remains — iteration 2's shell may have forked-and-exec'd but not yet installed its sleep — so the test is tagged `@flaky-retry(3)`, but the wait-for-pid1-exit pattern is sufficient to keep retries below ~1% in practice on healthy CI. Assert: (a) loopx exits 130 (SIGINT, 128 + 2) immediately — between-iterations cleanup is fast, no child grace-period applies, and no iteration-2 child process remains (verify via `kill(pid1, 0) === ESRCH` and the absence of a new `"ready-iter-2"` line on stderr); if the residual race lost (signal arrived during iteration 2's child), the test retries. (b) The tmpdir path read from the marker no longer exists on disk (cleanup ran before exit, per SPEC 7.3 / 7.4 — and matched the immediate-cleanup-no-child clause from SPEC 7.3). Also run a SIGTERM variant (assert exit 143) by parameterizing the test over `[SIGINT → 130, SIGTERM → 143]`. `@flaky-retry(3)`. Known residual gap — see section 1.3. *(Spec 7.3, 7.4)*
 - **T-SIG-08**: Signal identity preserved (SIGINT forwarded as SIGINT, SIGTERM as SIGTERM). *(Spec 7.3)*
 
+#### Pre-iteration Signal-Wins Precedence
+
+SPEC 7.3 defines a CLI-specific rule: SIGINT / SIGTERM observed by loopx's installed pre-iteration signal handler **wins** over non-signal pre-iteration failures not yet surfaced at that point. loopx cleans up any partial tmpdir and exits with `128 + signal number` regardless of which non-signal pre-iteration step (target syntax validation, `.loopx/` discovery, env-file loading, target resolution, tmpdir creation) would otherwise have failed. These tests cover the rule across the enumerated failure modes.
+
+All tests in this block use `runCLIWithSignal` to deliver the signal during the pre-iteration window. Each test combines a non-signal pre-iteration failure (configured to fail deterministically) with a signal delivered before the failure surfaces, then asserts the signal-exit-code outcome rather than the failure-exit-code outcome. To synchronize signal delivery with the pre-iteration window, the harness relies on the **pre-iteration sentinel stderr marker** declared as a test-only seam in section 1.4: `waitForStderr(<implementation-defined sentinel>)` observes the line emitted by loopx at pre-iteration start (after signal-handler installation, before discovery / env-file loading / target resolution / tmpdir creation), then delivers the signal during the remaining pre-iteration window. **Each test in this block must set `LOOPX_TEST_PREITERATION_SENTINEL=1` in loopx's inherited environment** (in addition to the standard `NODE_ENV=test`) to opt into sentinel emission; without this dedicated flag, loopx must not emit the sentinel and the harness falls back to a real-time delay (see section 1.4 for why the dedicated flag is required rather than `NODE_ENV=test` alone). Because the sentinel is a test-only seam (not a SPEC requirement — see section 1.4), these tests are tagged `@flaky-retry(3)` to tolerate environments where the sentinel is unavailable or harness timing drifts; a short real-time delay before signaling is the fallback synchronization strategy in that case. As an additional robustness lever, a slow pre-iteration step (e.g., a `.loopx/` layout with many workflow subdirectories to scan) widens the pre-iteration window and reduces the retry rate.
+
+- **T-SIG-20**: Signal during pre-iteration wins over missing env file. Configure a slow pre-iteration (e.g., a `.loopx/` layout with many workflow subdirectories to scan), a missing `-e nonexistent.env`, and a valid workflow target. Start loopx via `runCLIWithSignal`, deliver SIGINT during the pre-iteration window. Assert: exit code 130 (not 1), and stderr does not emit the missing-env-file error as the fatal-exit reason — the signal displaced it. `@flaky-retry(3)`. *(Spec 7.3)*
+- **T-SIG-21**: Signal during pre-iteration wins over missing workflow. Configure a `.loopx/` with many sibling workflows (slow discovery) and target a non-existent workflow (`loopx run nonexistent-workflow`). Deliver SIGINT during the pre-iteration window. Assert exit code 130 (not 1), and no missing-workflow error is the fatal-exit reason. `@flaky-retry(3)`. *(Spec 7.3)*
+- **T-SIG-22**: Signal during pre-iteration wins over invalid target. Configure the same slow-pre-iteration fixture; target `":script"` (invalid target format per SPEC 4.1). Deliver SIGINT during pre-iteration. Assert exit code 130, not 1 for invalid-target. `@flaky-retry(3)`. *(Spec 7.3)*
+- **T-SIG-23**: Signal during pre-iteration wins over tmpdir creation failure. Configure `TMPDIR` to an unwritable path (like T-TMP-12a), and a valid target. Deliver SIGINT during pre-iteration. Assert exit code 130 (not 1 for tmpdir creation failure). Additionally assert no `loopx-*` directory is left behind under the test-isolated tmpdir parent — i.e., the configured unwritable path's directory tree is unchanged (no partial `loopx-*` entry was created and not cleaned up); signal-wins still honors the best-effort cleanup clause from SPEC 7.4. Assertion scope: only the configured unwritable parent / test-isolated `TMPDIR` is inspected (per the test-parent isolation guidance in section 4.7's tmpdir-block preface), not `os.tmpdir()` globally — a global scan would race with concurrent test workers creating their own `loopx-*` entries elsewhere. `@flaky-retry(3)`. **Conditional on `process.getuid() !== 0`.** *(Spec 7.3, 7.4)*
+- **T-SIG-24**: Signal during pre-iteration wins over missing `.loopx/` directory. SPEC 7.3 enumerates `.loopx/` discovery as one of the non-signal pre-iteration failure modes displaced by the signal-wins rule. Set the fixture cwd to a directory with **no** `.loopx/` subdirectory (the standard missing-`.loopx/` condition from T-CLI-42 / T-DISC-10a). Target any workflow (e.g., `loopx run ralph`). Start loopx via `runCLIWithSignal`, deliver SIGINT during the pre-iteration window (synchronize via the sentinel stderr marker). Assert: (a) exit code 130 (not 1 for missing `.loopx/`), (b) stderr does not surface the missing-`.loopx/` error as the fatal-exit reason — the signal displaced it. Discovery-failure counterpart to T-SIG-20 (missing env file) and T-SIG-21 (missing workflow). `@flaky-retry(3)`. *(Spec 7.3, 5.1)*
+- **T-SIG-25**: Signal during pre-iteration wins over discovery-time sibling validation failure. Set up a `.loopx/` layout where the target workflow (`ralph`) is valid, but a sibling workflow has an invalid script name (e.g., `.loopx/broken/-bad.sh`) or invalid workflow name (e.g., `.loopx/-bad-workflow/index.sh`) that would cause discovery validation to fail (T-DISC-47a / T-DISC-47b territory). Target `loopx run ralph`. Deliver SIGINT during the pre-iteration window while discovery is scanning. Assert: (a) exit code 130 (not 1 for the discovery validation failure), (b) stderr does not surface the discovery-validation error as the fatal-exit reason — the signal displaced it. This is the sibling-validation counterpart to T-SIG-24 (missing `.loopx/`): both exercise the SPEC 7.3 enumerated "`.loopx/` discovery" failure mode, but T-SIG-25 hits the validation-scope sub-path (SPEC 5.4) rather than the existence sub-path. `@flaky-retry(3)`. *(Spec 7.3, 5.1, 5.3, 5.4)*
+- **T-SIG-20a**: SIGTERM variant of the pre-iteration signal-wins rule. Per SPEC 7.3 "Pre-iteration signal-wins precedence (CLI)": the rule applies to **SIGINT / SIGTERM** — not SIGINT alone. T-SIG-20 through T-SIG-25 all use SIGINT; this test parameterizes the same coverage over SIGTERM to pin down that the precedence rule is signal-agnostic across the two. Use the same slow-pre-iteration fixture as T-SIG-20 (a `.loopx/` layout with many workflow subdirectories), a missing `-e nonexistent.env`, and a valid workflow target. Start loopx via `runCLIWithSignal`, deliver **SIGTERM** during the pre-iteration window. Assert: (a) exit code **143** (128 + 15 for SIGTERM, not 1 for the missing-env-file error), (b) stderr does not surface the missing-env-file error as the fatal-exit reason — the signal displaced it. Together with T-SIG-20/21/22/23/24/25 (SIGINT across the five enumerated pre-iteration failure modes), this test closes the SIGTERM gap across the rule — it is sufficient to prove SIGTERM enters the precedence pathway; the cross-product of SIGTERM × all five failure modes is not required because the precedence rule is defined per-signal (not per-failure-mode-per-signal), and the shared-rule nature is established by the shared "SIGINT / SIGTERM" phrasing in SPEC 7.3. `@flaky-retry(3)`. *(Spec 7.3, 8.2)*
+- **T-SIG-27**: Signal during pre-iteration wins over missing script in an existing workflow. SPEC 7.1 target resolution (step 3) has three sub-paths — missing workflow, missing script in an existing workflow, and missing default `index` for a bare workflow target — and SPEC 7.3's pre-iteration signal-wins rule covers target resolution as a single enumerated failure mode. T-SIG-21 covers the missing-workflow sub-path; this test covers the missing-script sub-path. Set up `.loopx/ralph/index.sh` (the workflow exists and has `index`) but no `check` script. Target `loopx run ralph:check`. Start loopx via `runCLIWithSignal` with the slow-pre-iteration fixture from T-SIG-20 (many sibling workflow subdirectories to widen the pre-iteration window), set `LOOPX_TEST_PREITERATION_SENTINEL=1`, and deliver SIGINT during the pre-iteration window (synchronize via the sentinel stderr marker from section 1.4). Assert: (a) exit code 130 (not 1 for the missing-script error), (b) stderr does not surface the missing-script error as the fatal-exit reason — the signal displaced it. Together with T-SIG-21 (missing workflow), this test pins down that both enumerated target-resolution sub-paths for a qualified `workflow:script` target are covered by the pre-iteration signal-wins rule. `@flaky-retry(3)`. *(Spec 7.3, 7.1, 4.1)*
+- **T-SIG-28**: Signal during pre-iteration wins over missing default `index` for a bare workflow target. SPEC 7.1 target resolution's third sub-path: a bare workflow target `loopx run ralph` resolves to `ralph:index`, which fails with a distinct missing-default-entry-point error when the workflow has scripts but no `index`. Set up `.loopx/ralph/check.sh` only (no `index.*`) — the workflow exists but has no default entry point. Target bare `loopx run ralph`. Start loopx via `runCLIWithSignal` with the slow-pre-iteration fixture from T-SIG-20, set `LOOPX_TEST_PREITERATION_SENTINEL=1`, and deliver SIGINT during the pre-iteration window. Assert: (a) exit code 130 (not 1 for the missing-default-entry-point error), (b) stderr does not surface the missing-default-entry error as the fatal-exit reason — the signal displaced it. Together with T-SIG-21 (missing workflow) and T-SIG-27 (missing qualified script), this test closes the third target-resolution sub-path enumerated in SPEC 7.1 step 3 — the API counterparts are T-API-65h / T-API-65i / T-API-65j, which prove abort-precedence over the same three sub-paths on the programmatic surface. `@flaky-retry(3)`. *(Spec 7.3, 7.1, 4.1, 2.1)*
+- **T-SIG-30**: Signal during pre-iteration wins over **unreadable global env file**. SPEC 7.3's pre-iteration signal-wins rule covers env-file loading as one of the enumerated displaced failure modes; T-SIG-20 covers a **missing local** `-e` env file, but the **global env file unreadable-permission** sub-path (SPEC 8.1 / SPEC 7.1 step 2) is not exercised. Without this case, an implementation that handled missing local env files via the signal-wins precedence path but routed unreadable global env files through a different, signal-blind code path (e.g., a synchronous `fs.readFileSync` that throws and is rethrown before signal observation) could regress in the global-env branch undetected. Set up: an isolated `XDG_CONFIG_HOME` (e.g., `<test-dir>/xdg-config`) with `loopx/env` written and then `chmod 000`'d so it exists but is unreadable; this `XDG_CONFIG_HOME` is injected into loopx's inherited environment (the same injection pattern as T-TMP-12-global-env-unreadable — `RunOptions.env` does not affect global-env path resolution per SPEC 8.1). A valid `.loopx/ralph/index.sh` and the slow-pre-iteration fixture from T-SIG-20 (many sibling workflow subdirectories to widen the pre-iteration window). Set `LOOPX_TEST_PREITERATION_SENTINEL=1`. Run two variants:
+    - **(30-sigint)**: Start loopx via `runCLIWithSignal`, deliver **SIGINT** during the pre-iteration window (synchronize via the sentinel stderr marker). Assert: (a) exit code 130 (not 1 for the unreadable-global-env-file error), (b) stderr does not surface the global-env-file-read error as the fatal-exit reason — the signal displaced it.
+    - **(30-sigterm)**: Same setup but deliver **SIGTERM**. Assert: (a) exit code 143 (not 1), (b) stderr does not surface the global-env-file-read error.
+
+  This is the global-env-file counterpart to T-SIG-20 (missing local `-e` env file). T-SIG-20a parameterizes the missing-local-env case over SIGTERM; this test parameterizes both SIGINT and SIGTERM together since the two sub-cases are about the same underlying global-env-unreadable failure mode and the cost of running both is small. `@flaky-retry(3)`. **Conditional on `process.getuid() !== 0`** (root can read mode-000 files, defeating the unreadable setup). *(Spec 7.3, 8.1, 7.1)*
+
+#### Pre-handler-installation Window (Known Gap)
+
+SPEC 7.3 also defines behavior for signals delivered **before** loopx has installed its
+pre-iteration signal handlers: those signals are outside the signal-wins precedence rule,
+and either default POSIX signal termination or a parser-level usage error is conforming.
+That startup window is not widened or exposed by the current harness.
+
+- **T-SIG-26 (not yet directly covered)**: Signal delivered before pre-iteration signal-handler installation. Deterministic coverage would require a startup-delay seam before handler installation; without that seam, this clause remains an explicit known gap rather than claimed coverage.
+
+#### Narrow Pre-iteration Windows (Known Gaps)
+
+SPEC 7.3 / 7.4 / 9.3 also imply behavior for signals / aborts delivered in narrow windows inside pre-iteration that the current harness does not deterministically expose. These remain explicit known gaps unless a test-only seam (e.g., a pre-spawn synchronization sentinel that blocks between tmpdir creation and first child spawn, or a tmpdir-creation pause sentinel that blocks during a partial creation step) is added.
+
+- **T-SIG-29 (not yet directly covered)**: CLI signal delivered after `LOOPX_TMPDIR` has been created but before the first child spawn. SPEC 7.4 specifies that cleanup runs when `LOOPX_TMPDIR` has been created; combined with SPEC 7.3's signal-handling rules, a SIGINT / SIGTERM delivered in this narrow window (post-tmpdir-creation, pre-first-spawn) must still observe the signal exit code and run tmpdir cleanup before exit. T-SIG-07a covers the between-iterations window (where a child has already run at least once), T-SIG-20 through T-SIG-25 / T-SIG-27 / T-SIG-28 cover pre-tmpdir-creation failure modes, and T-SIG-23 covers tmpdir-creation-failure specifically — none cover the tiny "tmpdir created, no child spawned yet" window. Deterministic coverage would require an implementation-defined sentinel emitted after tmpdir creation and before first-child-spawn (analogous to the pre-iteration sentinel in section 1.4 but later in the sequence). Until such a seam is declared, this remains a known gap — the window is narrow enough that incidental coverage by flaky timing is possible but not claimed as conformance coverage.
+- **T-API-10i (not yet directly covered)**: Programmatic abort (via `AbortController.abort()` on a `RunOptions.signal`) delivered during pre-iteration but before the first child spawn. SPEC 9.3 enumerates "abort during pre-iteration before the first child spawn" as an abort case that displaces other pre-iteration failures. T-API-10b covers pre-aborted signal at call time (signal already aborted when `run()` / `runPromise()` is called), T-API-65 through T-API-65o cover pre-aborted-signal precedence over enumerated pre-iteration failures, and T-API-10a covers abort-during-active-child — but no test covers abort delivered **during** the pre-iteration sequence itself (e.g., in the window between the consumer calling `gen.next()` and loopx capturing the signal, or during discovery / env-file loading / target resolution / tmpdir creation). Deterministic coverage would require a programmatic pre-iteration sentinel / delay seam analogous to `LOOPX_TEST_PREITERATION_SENTINEL` but hook-exposed to the API-driver harness, so the driver can synchronize `c.abort()` with the pre-iteration window. Without such a seam, this sub-path is only exercised via incidental timing races. Tracked as a known coverage limitation of SPEC 9.3's pre-iteration abort-precedence surface.
+- **T-SIG-30b / T-API-10j (not yet directly covered)**: Signal or abort delivered concurrently with a tmpdir creation failure (partial-creation racing-cleanup window). SPEC 7.4's creation-failure handling clause states: "If a SIGINT/SIGTERM or `AbortSignal` abort arrives concurrently with a creation failure, the signal/abort wins and any partial directory is cleaned up under the same rules." SPEC 7.2's cleanup-idempotence enumeration also names "abort concurrent with tmpdir creation failure" as a covered race. Current tests cover the constituent halves separately: T-TMP-12a/b/c cover `mkdtemp` failure with no partial directory and no concurrent signal/abort; T-API-65d / T-API-65n cover programmatic abort-displaces-tmpdir-creation-failure where the signal is captured at call time (already-aborted) rather than racing with the partial-creation window; T-SIG-23 covers CLI signal precedence over tmpdir-creation-failure where the signal arrives before the partial directory exists; T-TMP-12d / T-TMP-12e / T-TMP-12d2 / T-TMP-12e2 cover identity-capture and mode-secure failures (with and without follow-on cleanup-failure) without a concurrent signal/abort. None cover the SPEC 7.4 narrow window where `mkdtemp` has succeeded and produced a partial directory but identity capture or mode-securing has not yet failed (or has just failed and the surface has not yet observed the failure), and a signal/abort arrives during that window. Deterministic coverage would require a new `LOOPX_TEST_TMPDIR_CREATION_PAUSE` pause sentinel with at least two ordinal window values — `after-mkdtemp-before-identity` (pauses between sub-steps 1 and 2 of SPEC 7.4's creation order so the harness can deliver the signal/abort while a partial directory exists with no identity recorded yet) and `creation-failure-observed-before-surface` (pauses after a creation-step failure has been observed but before the surface dispatches the failure, so the harness can race a signal/abort with the failure-cleanup path). Until such a seam is declared, the SPEC 7.4 "signal/abort wins and any partial directory is cleaned up under the same rules" guarantee is observed only via incidental timing races and is not claimed as conformance coverage. The minimum coverage that the seam would unlock is: (i) CLI SIGINT/SIGTERM during partial creation → signal exit code (`128 + N`), partial directory cleaned or left according to the applicable creation-failure cleanup rule, at most one cleanup warning; (ii) programmatic abort during partial creation → abort error surfaces, partial directory handled correctly, at most one cleanup warning. Tracked as a known coverage limitation of SPEC 7.4's signal-wins-over-creation-failure clause.
+
 ### 4.12 CLI Delegation
 
 **Spec refs:** 3.2
@@ -1596,11 +3267,14 @@ The "global" binary is the primary build. The "local" binary is a separate build
 - **T-DEL-02**: Delegation checks CWD only, not ancestor directories. Create a parent directory with a `package.json` that declares `loopx` as a dependency and a corresponding `node_modules/.bin/loopx`. Run loopx from a child directory (which has no `node_modules/.bin/loopx` and no `package.json`). Assert the global binary runs (no delegation). The parent must have a `package.json` declaring `loopx` so the test proves ancestor traversal was actually removed — without it, the test could pass for the weaker reason that the parent binary is undeclared (per T-DEL-16), not because ancestor traversal is not performed. *(Spec 3.2)*
 - **T-DEL-03**: Delegation works before `.loopx/` exists. Run `loopx version` from a project root that has `package.json` declaring loopx and `node_modules/.bin/loopx`. Assert the local binary handles the command. *(Spec 3.2)*
 - **T-DEL-04**: `LOOPX_DELEGATED=1` in environment prevents delegation. Even if `node_modules/.bin/loopx` exists, the global binary runs. *(Spec 3.2)*
+- **T-DEL-04a**: `LOOPX_DELEGATED=1` short-circuits delegation **before** the project-root `package.json` is even read — no parse warning is emitted on a broken `package.json`. T-DEL-04 covers the recursion guard with a clean `package.json` shape; this test pins down that the guard runs early enough that loopx does not consult the project-root `package.json` at all when the env var is set, so a malformed `package.json` neither parsed nor warned about. T-DEL-13 / T-DEL-14 cover broken `package.json` shapes *without* the recursion guard (delegation is skipped with a parse warning). The combination — broken `package.json` *with* the recursion guard set — must produce **neither** delegation **nor** the parse warning, because the guard exits the delegation code path before any `package.json` access. A buggy implementation that read and validated the project-root `package.json` first and then consulted `LOOPX_DELEGATED` would emit the parse warning here in addition to skipping delegation, failing assertion (c). Set up a project root with a broken `package.json` (e.g., `{broken` — invalid JSON, same shape as T-DEL-14) and a marker-writing `node_modules/.bin/loopx`. Run `loopx version` via the global binary with `LOOPX_DELEGATED=1` set in the inherited environment. Assert: (a) the global install runs (the marker file is NOT created — delegation is skipped because the env var is set), (b) exit code 0 with the global version string, and (c) stderr contains **no** `package.json` parse warning (the recursion guard prevented loopx from reading the project-root `package.json` at all — the broken file is never touched). The marker binary's absence proves delegation did not happen; the absence of a parse warning proves the project-root `package.json` was never read. *(Spec 3.2)*
 - **T-DEL-05**: After delegation, `LOOPX_BIN` contains the resolved realpath of the local binary (not the global one, not a symlink). *(Spec 3.2)*
 - **T-DEL-06**: After delegation, `import from "loopx"` in scripts resolves to the **local (delegated-to) version's** package. The local (delegated-to) `node_modules/loopx` package must export a sentinel value that differs from the global CLI's package. The test script imports from `"loopx"` and writes the sentinel to a marker file. Assert: the marker file contains the delegated package's sentinel, proving module resolution actually points to the local version and not just that delegation occurred at the binary level. *(Spec 3.2, 3.3)*
 - **T-DEL-07**: Delegation sets `LOOPX_DELEGATED=1` in the delegated process. *(Spec 3.2)*
+- **T-DEL-07a**: After delegation actually fires, scripts spawned by the delegated loopx observe `LOOPX_DELEGATED=1` in their per-spawn environment via the standard env-tier merge — i.e., `LOOPX_DELEGATED` is set on the delegated loopx process (per T-DEL-07) and inherited normally into the inherited-`process.env` tier visible to spawned scripts (per T-ENV-24a's "not scrubbed before spawning" rule), absent a higher-tier override. T-DEL-07 verifies the delegated loopx process itself receives `LOOPX_DELEGATED=1`; T-ENV-24a verifies that a user-supplied `LOOPX_DELEGATED` reaches scripts via inherited environment; this test combines those into the realistic end-to-end case where delegation fires for real and the inherited value the delegated loopx received then flows through to the spawned script. Set up: a project root with `package.json` declaring `loopx` and a `node_modules/.bin/loopx` (the delegated binary — same fixture pattern as T-DEL-01). The delegated loopx is the implementation under test (so spawning a child script works correctly). Create `.loopx/ralph/index.sh` that uses the `observe-env` fixture for `LOOPX_DELEGATED` and emits `stop:true`. Run `loopx run -n 1 ralph` via the global binary (i.e., the one that delegates to `node_modules/.bin/loopx`) **without** `LOOPX_DELEGATED` set in the inherited environment of the global invocation (so delegation actually fires). Assert: (a) delegation fired (verified by a marker pattern equivalent to T-DEL-01's local-binary marker, or by observing that the delegated path's binary wrote any side-effect proving it ran), (b) the script's `observe-env` marker for `LOOPX_DELEGATED` records `{ "present": true, "value": "1" }` — i.e., the delegated loopx's own `LOOPX_DELEGATED=1` startup-reserved value was inherited normally into the spawned script's environment per SPEC 3.2 + 8.3 + 13's "startup-reserved-only, inherited normally" rule, and (c) exit code 0. This pins down the realistic post-delegation behavior on the inheritance side, where T-DEL-07 (the delegated process gets `LOOPX_DELEGATED=1`) and T-ENV-24a (`LOOPX_DELEGATED` is not scrubbed before spawn) interact. A buggy implementation that **scrubbed** `LOOPX_DELEGATED` from the spawn environment after delegation (e.g., to "clean up" startup-reserved variables) would pass T-DEL-07 (the delegated process received it) and T-ENV-24a (a user-supplied value reaches scripts) but fail this test (the delegation-injected value does not reach scripts). *(Spec 3.2, 8.3, 13)*
 - **T-DEL-08**: Delegation happens before command handling. Run global binary with `version` → local binary handles it. *(Spec 3.2)*
 - **T-DEL-09**: `LOOPX_DELEGATED=""` (empty string) prevents delegation. *(Spec 3.2)*
+- **T-DEL-09a**: `LOOPX_DELEGATED=0` (literal string `"0"`) prevents delegation. SPEC 3.2 says delegation is skipped when `LOOPX_DELEGATED` is **set** in the environment — "set" means any value, including the literal `"0"` (which is a non-empty string and therefore a present value, not an absence-equivalent). T-DEL-04 covers `LOOPX_DELEGATED=1` and T-DEL-09 covers `LOOPX_DELEGATED=""` (empty string is also "set" per env-var semantics). This test pins down that `"0"` is also "set" — a buggy implementation that interpreted `LOOPX_DELEGATED` as a boolean (where `"0"` / `"false"` / `"no"` map to "not set") rather than as a presence check would fail this test. Set up a project-root `package.json` declaring `loopx` and a `node_modules/.bin/loopx` marker binary; spawn `loopx version` via the global binary with `LOOPX_DELEGATED=0` in the inherited environment. Assert: (a) the global install runs (the marker binary is NOT invoked — assert via marker file absence), (b) exit code 0 with the global version string. The presence-check semantics are normative (SPEC 3.2 says "set", not "set to a truthy value"), so this test gates against the falsy-value-as-unset interpretation specifically. *(Spec 3.2)*
 - **T-DEL-10**: Delegation preserves SIGINT exit code (130). *(Spec 3.2, 7.3, 12)*
 - **T-DEL-11**: Delegation preserves SIGTERM exit code (143). *(Spec 3.2, 7.3, 12)*
 
@@ -1611,12 +3285,20 @@ The "global" binary is the primary build. The "local" binary is a separate build
 - **T-DEL-14**: Invalid JSON in `package.json` → warning on stderr. Delegation skipped, global runs. Place a marker-writing binary at `node_modules/.bin/loopx` in the project root. Create a `package.json` at the project root containing invalid JSON (e.g., `{broken`). Run `loopx version` via the global binary. Assert: (a) the global install runs (marker file is NOT created), (b) stderr contains a warning about the invalid JSON, and (c) exit code 0 with the global version string. Without the local binary in the fixture, "delegation skipped" passes without exercising the `package.json`-driven decision path. *(Spec 3.2)*
 - **T-DEL-14a**: Delegation failure warning on a non-version command. Same setup as T-DEL-14 (project root with invalid-JSON `package.json` and a marker-writing `node_modules/.bin/loopx`). Run `loopx install -h` via the global binary. Assert: (a) the global install runs (marker file is NOT created), (b) stderr contains a warning about the invalid JSON, and (c) exit code 0 with install help output. T-DEL-13 and T-DEL-14 prove delegation failure modes on `loopx version`; this proves the same failure-mode warnings fire for a non-version, non-run command, pinning down that delegation failure warnings happen before command parsing for all commands. *(Spec 3.2)*
 - **T-DEL-14b**: Delegation failure warning on bare invocation / top-level help. Same setup as T-DEL-14 (project root with invalid-JSON `package.json` and a marker-writing `node_modules/.bin/loopx`). Run bare `loopx` (no arguments) via the global binary. Assert: (a) the global install runs (marker file is NOT created — delegation was skipped due to the broken `package.json`), (b) stderr contains a warning about the invalid JSON, and (c) exit code 0 with top-level help output. T-DEL-13/T-DEL-14/T-DEL-14a prove delegation failure-mode warnings on `loopx version` and `loopx install -h`; this test extends failure-mode coverage to the bare-invocation / top-level-help path. T-DEL-22 and T-DEL-23 cover the positive (successful) delegation case on top-level help and bare invocation respectively; this test covers the negative (skipped-with-warning) case, pinning down that the "delegation happens before command parsing for all commands" rule holds on that path even when delegation is skipped. *(Spec 3.2)*
-- **T-DEL-15**: `loopx` declared in `package.json` but `node_modules/.bin/loopx` does not exist → warning on stderr. Delegation skipped, global runs. *(Spec 3.2)*
+- **T-DEL-15**: `loopx` declared in `package.json` `dependencies` but `node_modules/.bin/loopx` does not exist → warning on stderr. Delegation skipped, global runs. SPEC 3.2 explicitly enumerates three checked dependency fields (`dependencies`, `devDependencies`, `optionalDependencies`); this test covers the `dependencies` field. The two sibling tests T-DEL-15a and T-DEL-15b extend coverage to the other two checked fields. *(Spec 3.2)*
+- **T-DEL-15a**: `loopx` declared in `package.json` `devDependencies` (only — not in `dependencies` or `optionalDependencies`) but `node_modules/.bin/loopx` does not exist → warning on stderr. Delegation skipped, global runs. Per SPEC 3.2: "Valid JSON, `loopx` declared in `dependencies`/`devDependencies`/`optionalDependencies`, but `node_modules/.bin/loopx` does not exist: A warning is printed to stderr ... Delegation is skipped and the global install runs." T-DEL-15 covers `dependencies`; this test covers `devDependencies`. T-DEL-18 covers the **positive** delegation case for `devDependencies` (binary present); this test covers the missing-binary warning case for the same field. A buggy implementation that emitted the missing-binary warning only for `dependencies` (and silently skipped delegation for `devDependencies` with the binary missing) would fail this test. *(Spec 3.2)*
+- **T-DEL-15b**: `loopx` declared in `package.json` `optionalDependencies` (only — not in `dependencies` or `devDependencies`) but `node_modules/.bin/loopx` does not exist → warning on stderr. Delegation skipped, global runs. Same SPEC 3.2 enumerated rule as T-DEL-15 / T-DEL-15a. T-DEL-17 covers the **positive** delegation case for `optionalDependencies` (binary present); this test covers the missing-binary warning case for that field. A buggy implementation that scoped the missing-binary warning to `dependencies` + `devDependencies` and silently skipped on `optionalDependencies` would fail this test. Together with T-DEL-15 / T-DEL-15a, this completes the "declared but binary missing → warning" coverage across all three SPEC-3.2-enumerated dependency fields, mirroring T-DEL-17 / T-DEL-18 / (T-DEL-15-positive-which-doesn't-exist-as-an-explicit-test-because-T-DEL-01–05-already-covers-`dependencies`-positive-delegation) on the positive side. *(Spec 3.2)*
 - **T-DEL-16**: `node_modules/.bin/loopx` exists but `loopx` not declared in any dependency field → no delegation, no warning. The binary is undeclared. *(Spec 3.2)*
 - **T-DEL-17**: Project-root `package.json` declares `loopx` in `optionalDependencies` (not `dependencies` or `devDependencies`) and `node_modules/.bin/loopx` exists → delegation occurs. `optionalDependencies` is checked at the project root level for locating a local binary. *(Spec 3.2)*
 - **T-DEL-18**: Project-root `package.json` declares `loopx` in `devDependencies` (not `dependencies` or `optionalDependencies`) and `node_modules/.bin/loopx` exists → delegation occurs. `devDependencies` is checked at the project root level for locating a local binary. *(Spec 3.2)*
-- **T-DEL-27**: Project-root `package.json` declares `loopx` only in `peerDependencies` (not in `dependencies`, `devDependencies`, or `optionalDependencies`) and `node_modules/.bin/loopx` exists → no delegation, no warning. Per SPEC 3.2, project-root delegation checks only `dependencies`, `devDependencies`, and `optionalDependencies` — `peerDependencies` is not one of the enumerated fields. Place a marker-writing binary at `node_modules/.bin/loopx` in the project root so a delegatable binary exists on the filesystem. Create a project-root `package.json` declaring `loopx` only under `peerDependencies` with any range. Run `loopx version` via the global binary. Assert: (a) the global install runs (marker file is NOT created), (b) stderr contains no warning (this is the "not declared in any checked dependency field" path from T-DEL-16, not the "declared but binary missing" path from T-DEL-15), and (c) exit code 0 with the global version string. T-DEL-17 / T-DEL-18 prove the positive cases for `optionalDependencies` and `devDependencies`, and T-DEL-16 proves the "no declaration" case; this closes the gap by proving that `peerDependencies` is not implicitly treated as one of the checked fields. **Classification:** derived-spec coverage, not core ADR-0003 acceptance coverage. SPEC 3.2 enumerates the three delegation-checked fields explicitly (`dependencies`, `devDependencies`, `optionalDependencies`) but does not explicitly discuss `peerDependencies`; this test validates an exclusion that follows from the enumerated-list semantics rather than from a direct ADR-0003 statement. Keep as a useful boundary test, but do not gate ADR-0003 acceptance on it. *(Spec 3.2)*
+- **T-DEL-27**: Project-root `package.json` declares `loopx` only in `peerDependencies` (not in `dependencies`, `devDependencies`, or `optionalDependencies`) and `node_modules/.bin/loopx` exists → no delegation, no warning. Per SPEC 3.2, project-root delegation checks only `dependencies`, `devDependencies`, and `optionalDependencies` — `peerDependencies` is not one of the enumerated fields, so a `loopx` declaration there is invisible to the delegation check. Place a marker-writing binary at `node_modules/.bin/loopx` in the project root so a delegatable binary exists on the filesystem. Create a project-root `package.json` declaring `loopx` only under `peerDependencies` with any range. Run `loopx version` via the global binary. Assert: (a) the global install runs (marker file is NOT created), (b) stderr contains no warning (this is the "not declared in any checked dependency field" path from T-DEL-16, not the "declared but binary missing" path from T-DEL-15), and (c) exit code 0 with the global version string. T-DEL-17 / T-DEL-18 prove the positive cases for `optionalDependencies` and `devDependencies`, and T-DEL-16 proves the "no declaration" case; this closes the gap by proving that `peerDependencies` is not implicitly treated as one of the checked fields. *(Spec 3.2)*
 - **T-DEL-19**: Delegation is presence-based, not range-based. Project-root `package.json` declares `loopx` in `dependencies` with a semver range NOT satisfied by the local binary's actual version (e.g., `"loopx": "^99.0.0"`), and `node_modules/.bin/loopx` exists → delegation still occurs. The global binary delegates based on declaration presence and binary existence, without comparing the declared range against the local binary's version. Verify by having the local binary write a marker file. *(Spec 3.2)*
+- **T-DEL-28**: Delegation is presence-based even when the declared range is **invalid semver**. T-DEL-19 covers a valid-but-unsatisfied range; this test extends coverage to the invalid-range path. SPEC 3.2's project-root delegation rule reads only "lists `loopx` as a dependency ... and a corresponding `node_modules/.bin/loopx` exists" — there is no semver-validity precondition. Whereas workflow-level version checking emits an "invalid semver range" warning and skips the check (T-VER-09 / T-VER-12a etc.), project-root delegation must not consult the range at all and must not warn about its shape, because the binary's existence — not the declared range — drives delegation. Set up a project-root `package.json` declaring `loopx` in `dependencies` with an **invalid semver range** (e.g., `{ "dependencies": { "loopx": "not-a-range!!!" } }`) and place a marker-writing binary at `node_modules/.bin/loopx`. Run `loopx version` via the global binary. Assert: (a) **delegation still occurs** — the local binary's marker file is created (the global binary delegated to the local one), (b) stderr contains **no invalid-semver warning** (project-root delegation does not parse or validate the range), and (c) exit code 0 with the local binary's version string. T-DEL-19 covers `valid-range, not-satisfied → delegate`; T-DEL-13 / T-DEL-14 cover `package.json` parse failures (unreadable, invalid JSON) where delegation **is** skipped with a warning (those failures prevent loopx from determining whether the dependency is declared at all). This test covers the third axis: the JSON is valid and the dependency is declared, but the range string itself is malformed — a path that would intuit "treat as a degraded / failed declaration" but per SPEC 3.2 must remain a delegation-eligible declaration. A buggy implementation that gated delegation on `semver.validRange(declaredRange)` would skip delegation here and fail this test. *(Spec 3.2)*
+- **T-DEL-28a**: Delegation is presence-based even when the declared range is **invalid semver and the binary is missing** — the missing-binary warning fires, no invalid-semver warning fires, and the global install runs. T-DEL-28 covers the invalid-range × binary-present case (delegation occurs). This test covers the missing-binary counterpart on the same invalid-range axis: declaration is present (so the SPEC 3.2 declared-and-binary-missing branch fires the warning) and the range is invalid (which must remain unconsulted — no parse, no validation, no semver-related warning). Together, T-DEL-28 and T-DEL-28a pin down that project-root delegation never parses or validates the declared range — neither when the binary is present (delegation succeeds) nor when the binary is missing (delegation skipped with the missing-binary warning, but **not** an invalid-semver warning). T-DEL-15 / T-DEL-15a / T-DEL-15b cover the missing-binary warning across the three checked dependency fields with valid (unspecified-shape) ranges; this test extends the missing-binary path to the invalid-range axis. Set up a project-root `package.json` declaring `loopx` in `dependencies` with an **invalid semver range** (e.g., `{ "dependencies": { "loopx": "not-a-range!!!" } }`) and **no `node_modules/.bin/loopx`** at the project root (the binary is absent). Run `loopx version` via the global binary. Assert: (a) the **global** install runs (no marker file is created — delegation is skipped because the binary is absent, matching T-DEL-15's missing-binary behavior), (b) stderr contains **exactly one** delegation-related warning, and that warning is the **missing-binary** warning (the same warning class as T-DEL-15 / T-DEL-15a / T-DEL-15b — the binary is declared but not on disk), (c) stderr contains **no invalid-semver warning** for the malformed range (project-root delegation does not parse or validate the range, regardless of whether the binary is present or missing — the missing-binary warning is the only delegation-related warning that fires on this configuration), and (d) exit code 0 with the global version string. A buggy implementation that gated the missing-binary warning on `semver.validRange(declaredRange)` would emit an invalid-semver warning instead of the missing-binary warning (or in addition to it), failing assertion (c). An implementation that conflated the two warning classes (e.g., emitted a single combined warning text mentioning both "invalid range" and "binary missing") would also fail assertion (c). This reinforces that project-root delegation is **declaration-presence × binary-presence based** and does not validate the declared range at any decision point on either branch. *(Spec 3.2)*
+- **T-DEL-28b**: Field-parity for invalid-range × binary-present on `devDependencies`. T-DEL-28 covers the same case (invalid range, binary present, delegation occurs, no invalid-semver warning) on the `dependencies` field. SPEC 3.2 enumerates three checked dependency fields (`dependencies`, `devDependencies`, `optionalDependencies`) and the no-range-validation rule must hold on each — a buggy implementation that special-cased `dependencies` to skip range validation while still parsing the range on the other two fields would pass T-DEL-28 / T-DEL-28a but emit an invalid-semver warning here. Set up a project-root `package.json` declaring `loopx` in **`devDependencies`** (only — not in `dependencies` or `optionalDependencies`) with an **invalid semver range** (e.g., `{ "devDependencies": { "loopx": "not-a-range!!!" } }`) and place a marker-writing binary at `node_modules/.bin/loopx`. Run `loopx version` via the global binary. Assert: (a) **delegation occurs** — the local marker file is created, (b) stderr contains **no invalid-semver warning** for the malformed range, and (c) exit code 0 with the local binary's version string. *(Spec 3.2)*
+- **T-DEL-28c**: Field-parity for invalid-range × binary-missing on `devDependencies`. T-DEL-28a covers the same case (invalid range, binary missing, missing-binary warning, no invalid-semver warning) on the `dependencies` field. Same field-parity rationale as T-DEL-28b — the missing-binary path must also avoid range validation on every checked field. Set up a project-root `package.json` declaring `loopx` only in **`devDependencies`** with an **invalid semver range** and **no `node_modules/.bin/loopx`** at the project root. Run `loopx version` via the global binary. Assert: (a) the **global** install runs (no marker file), (b) stderr contains **exactly one** delegation-related warning, and that warning is the **missing-binary** warning (same warning class as T-DEL-15a), (c) stderr contains **no invalid-semver warning** for the malformed range, and (d) exit code 0 with the global version string. *(Spec 3.2)*
+- **T-DEL-28d**: Field-parity for invalid-range × binary-present on `optionalDependencies`. Same field-parity rationale as T-DEL-28b — the third checked field must also avoid range validation on the binary-present path. Set up a project-root `package.json` declaring `loopx` only in **`optionalDependencies`** with an **invalid semver range** and place a marker-writing binary at `node_modules/.bin/loopx`. Run `loopx version` via the global binary. Assert: (a) **delegation occurs** — the local marker file is created, (b) stderr contains **no invalid-semver warning** for the malformed range, and (c) exit code 0 with the local binary's version string. Together with T-DEL-28 / T-DEL-28b this completes the invalid-range × binary-present field-parity sweep across all three SPEC-3.2-enumerated dependency fields. *(Spec 3.2)*
+- **T-DEL-28e**: Field-parity for invalid-range × binary-missing on `optionalDependencies`. Same field-parity rationale as T-DEL-28c — the third checked field must also avoid range validation on the missing-binary path. Set up a project-root `package.json` declaring `loopx` only in **`optionalDependencies`** with an **invalid semver range** and **no `node_modules/.bin/loopx`** at the project root. Run `loopx version` via the global binary. Assert: (a) the **global** install runs (no marker file), (b) stderr contains **exactly one** delegation-related warning, and that warning is the **missing-binary** warning (same warning class as T-DEL-15b), (c) stderr contains **no invalid-semver warning** for the malformed range, and (d) exit code 0 with the global version string. Together with T-DEL-28a / T-DEL-28c this completes the invalid-range × binary-missing field-parity sweep across all three SPEC-3.2-enumerated dependency fields. The full T-DEL-28 / 28a / 28b / 28c / 28d / 28e family pins down that project-root delegation never parses or validates the declared range on **any** of the three checked fields and on **either** the binary-present or binary-missing branch. *(Spec 3.2)*
 - **T-DEL-20**: Workflow-local `package.json` and `node_modules/.bin/loopx` do not trigger delegation. Create a project root with no `package.json`. Create `.loopx/ralph/package.json` declaring `loopx` in `dependencies` and place a marker-writing binary at `.loopx/ralph/node_modules/.bin/loopx`. Create `.loopx/ralph/index.sh`. Run `loopx run -n 1 ralph`. Assert: (a) the global binary runs (marker file is NOT created), and (b) execution succeeds normally. Delegation is based on the project-root `package.json` only — workflow-level version declarations are not used for delegation. *(Spec 3.2)*
 - **T-DEL-21**: Delegation applies to non-version, non-run commands. Set up a project root with `package.json` declaring `loopx` in `dependencies` and a corresponding marker-writing `node_modules/.bin/loopx`. Run `loopx install -h` via the global binary. Assert the local binary handles the command (marker file created). This pins down that the simplified delegation model (cwd-only, command-agnostic, before command parsing) applies to commands beyond `version` and `run` — including commands that do not require `.loopx/`. *(Spec 3.2)*
 - **T-DEL-22**: Delegation applies to top-level help. Same delegation setup as T-DEL-21. Run `loopx -h` via the global binary. Assert the local binary handles the command (marker file created). Spec 3.2 says delegation happens before command parsing, so the top-level help short-circuit path must also delegate. This extends T-DEL-08 (version), T-DEL-21 (install -h) to the top-level help path. *(Spec 3.2)*
@@ -1625,11 +3307,14 @@ The "global" binary is the primary build. The "local" binary is a separate build
 #### Delegation × Version-Check Interaction
 
 - **T-DEL-24**: Runtime delegation × version checking. Set up delegation: project root `package.json` declares `loopx` in `dependencies` with `node_modules/.bin/loopx` present. The local (delegated-to) binary reports version `2.0.0`. Create `.loopx/ralph/index.sh` with a `package.json` declaring `"loopx": "^2.0.0"` in `dependencies`. Run `loopx run -n 1 ralph` via the global binary. Assert: (a) delegation occurs (local binary handles the command), and (b) no version mismatch warning on stderr — the version check compares the workflow's declared range against the delegated local version (`2.0.0`), not the global launcher version. This closes the gap between delegation (T-DEL-01–23) and runtime version checking (T-VER-01–25), which are each tested in isolation but never in combination. *(Spec 3.2)*
-- **T-DEL-25**: Install-time delegation × version checking. Same delegation setup as T-DEL-24: local binary reports version `2.0.0`. Source workflow declares `"loopx": "^2.0.0"` in its `package.json`. Run `loopx install <source>` via the global binary. Assert: (a) delegation occurs, (b) install succeeds without version mismatch error, and (c) the workflow is installed in `.loopx/`. The install-time version check must compare the workflow's declared range against the effective delegated version, not the global launcher version. *(Spec 3.2, 10.6)*
+- **T-DEL-25**: Install-time delegation × version checking. Same delegation setup as T-DEL-24: local binary reports version `2.0.0`. Source workflow declares `"loopx": "^2.0.0"` in its `package.json`. Run `loopx install --no-install <source>` via the global binary. Assert: (a) delegation occurs, (b) install succeeds without version mismatch error, and (c) the workflow is installed in `.loopx/`. The install-time version check must compare the workflow's declared range against the effective delegated version, not the global launcher version. **`--no-install` per the section 4.10 suite-wide auto-install-awareness rule** — the source workflow's top-level `package.json` would otherwise trigger the SPEC 10.10 post-commit auto-install pass, which is incidental to this test's contract (delegation × version-check) and would introduce real-`npm` flakiness on a scrubbed `PATH`. *(Spec 3.2, 10.6)*
 
 #### Additional Delegated Subcommand Coverage
 
 - **T-DEL-26**: Delegation applies to `env list`. Same delegation setup as T-DEL-21. Run `loopx env list` via the global binary. Assert the local binary handles the command (marker file created). T-DEL-08 covers `version`, T-DEL-21 covers `install -h`, T-DEL-22 covers `-h`, and T-DEL-23 covers bare invocation — this extends delegation coverage to a non-help, non-version, non-install subcommand, fully pinning down the "all commands" claim from Spec 3.2. *(Spec 3.2)*
+- **T-DEL-26a**: Delegation applies to `output`. Same delegation setup as T-DEL-21. Run `loopx output --result foo` via the global binary. Assert the local binary handles the command (marker file created with the global binary's argv recorded by the marker shim — including `output`, `--result`, and `foo`). T-DEL-08 covers `version`, T-DEL-21 covers `install -h`, T-DEL-22 covers `-h`, T-DEL-23 covers bare invocation, and T-DEL-26 covers `env list` — this test extends delegation coverage to the **`output`** built-in subcommand, completing "all commands" delegation coverage for the SPEC 4.3 / 11 enumerated built-ins (`run`, `version`, `output`, `env`, `install`). The `output` subcommand is the bash-script-helper surface from SPEC 6.4 and has its own argv parsing (`--result`, `--goto`, `--stop`); a buggy implementation that special-cased `output` to bypass delegation (perhaps because it's invoked from inside script execution and conceptually "downstream" of an already-running loopx) would skip delegation here and fail this test. The marker shim recording the global binary's argv proves the local binary received the `output --result foo` invocation byte-for-byte, not a re-parsed or re-encoded form. *(Spec 3.2, 4.3, 6.4)*
+- **T-DEL-29**: Delegation project-root derivation **ignores inherited `$PWD`** and uses loopx's own `process.cwd()`. SPEC 3.2 says "loopx does not consult `$PWD`" for project-root derivation, and SPEC 6.1 reiterates the rule for the CLI surface. T-PWD-06 covers the rule for **CLI run** project-root derivation (the `LOOPX_PROJECT_ROOT` injection path). Delegation itself reads from the same project-root surface — the global binary inspects the project root for a local `package.json` declaring loopx and a corresponding `node_modules/.bin/loopx` — and must therefore also ignore `$PWD`. A buggy implementation that consulted `$PWD` for the delegation lookup specifically (even if it correctly used `process.cwd()` for run-mode `LOOPX_PROJECT_ROOT`) could escape T-PWD-06 because the test surface is execution rather than delegation. Set up two directories: (a) a real project at `/tmp/no-deleg-cwd/` with **no** `package.json` and **no** `node_modules/.bin/loopx` (so cwd-based delegation lookup correctly finds nothing), and (b) a separate directory at `/tmp/has-deleg-pwd/` containing a `package.json` declaring `loopx` in `dependencies` plus a marker-writing `node_modules/.bin/loopx` shim. Spawn the **global** loopx binary with the spawn's `cwd` set to `/tmp/no-deleg-cwd/` and `PWD=/tmp/has-deleg-pwd/` in the inherited environment. Run `loopx version`. Assert: (a) the global install runs (the marker binary at `/tmp/has-deleg-pwd/node_modules/.bin/loopx` is **NOT** invoked — assert via marker file absence), (b) exit code 0 with the global version string, and (c) no warning on stderr (this is the "no `package.json` at project root" path — `process.cwd()` resolves to `/tmp/no-deleg-cwd/`, which legitimately has no `package.json`; loopx must not consult `PWD` to find one). A buggy implementation that consulted `$PWD` for the delegation `package.json` lookup would find `/tmp/has-deleg-pwd/package.json`, delegate to the marker shim, and fail (a). T-PWD-06 covers the run-time / `LOOPX_PROJECT_ROOT`-injection surface; this test closes the delegation surface gap. *(Spec 3.2, 6.1)*
+- **T-DEL-30**: Delegation happens **before command parsing**, including for usage-error inputs. SPEC 3.2 normatively says "Delegation happens **before command parsing**, so the entire session — CLI behavior, script helpers, and all — uses the pinned version." T-DEL-08 / T-DEL-21 / T-DEL-22 / T-DEL-23 / T-DEL-26 prove delegation for **valid** commands and the help short-circuits, but they do not prove that **parser-level errors** (unrecognized flags, malformed arguments) are also delegated to the local binary rather than rejected by the global parser before delegation can run. A buggy implementation that ran the parser first and short-circuited on usage errors before checking for delegation would pass every existing T-DEL-* test (those use valid inputs) while violating SPEC 3.2's "before command parsing" rule on the failure path. Set up a project root with `package.json` declaring `loopx` in `dependencies` and a marker-writing `node_modules/.bin/loopx`. Crucially, the marker shim **must record** that it was invoked (write a marker file with its argv) and then exit non-zero (e.g., `exit 2` to mimic a usage-error exit code without colliding with the success-path `exit 0` and without claiming to be a real loopx exit code). Run the **global** binary with a parser-level error input — pick **two** representative shapes to ensure the rule applies broadly: (a) `loopx --unknown` (unrecognized top-level flag, normally a SPEC 4.2 usage error), and (b) `loopx run --bogus ralph` (unrecognized run-scoped flag, normally a SPEC 4.2 usage error). For each invocation, assert: (i) the marker file exists with the corresponding argv (proving the local binary handled the command — delegation occurred), (ii) the global parser did **not** reject the input itself (the global binary delegated before parsing). The exit code from the global binary will reflect the local shim's exit (the global binary execs / spawns the local binary and proxies its exit code per SPEC 3.2's "the entire session ... uses the pinned version"); the test asserts that exit code matches the shim's chosen exit (`2` in this fixture). T-DEL-22 and T-DEL-23 prove delegation for the top-level help / bare-invocation short-circuits (which are *not* parser-level errors — they are valid argument shapes); this test closes the parser-error gap. A buggy implementation that ran the global parser first would (a) reject `--unknown` with a usage error before reaching the delegation check and (b) leave the marker file absent, failing the assertion. *(Spec 3.2, 4.2)*
 
 ### 4.13 Workflow-Level Version Checking
 
@@ -1651,26 +3336,38 @@ The "global" binary is the primary build. The "local" binary is a separate build
 - **T-VER-07f**: Cross-workflow `package.json` failure warning via goto — invalid semver range variant. Same structure as T-VER-07d: create `.loopx/clean/index.sh` (no `package.json` or a valid one with no loopx declaration) and `.loopx/broken/index.sh` with a `package.json` containing `{ "dependencies": { "loopx": "not-a-range!!!" } }` (valid JSON but invalid semver range). Set up a loop where `clean:index` gotos `broken:index`, and `broken:index` completes without goto (triggering loop reset). Run for multiple iterations. Assert: (a) the invalid-semver warning for `broken` is emitted exactly once on stderr (on first entry via goto), (b) no warning is emitted for `clean`, and (c) execution continues normally. This is the invalid-semver counterpart to T-VER-07d (invalid JSON) and T-VER-07e (unreadable). *(Spec 3.2)*
 - **T-VER-08**: Workflow `package.json` invalid JSON → warning, execution continues. *(Spec 3.2)*
 - **T-VER-09**: Workflow `package.json` invalid semver range → warning, execution continues. *(Spec 3.2)*
+- **T-VER-09a**: Workflow `package.json` `loopx` field is a **non-string** value → invalid-semver warning, execution continues. T-VER-09 covers an invalid-string range (e.g., `"not-a-range"`); this test covers the non-string-type path, which is also "not a valid semver range" but reaches that conclusion by type rather than by parse failure. Create `.loopx/ralph/index.sh` and `.loopx/ralph/package.json` containing `{ "dependencies": { "loopx": 42 } }` (a JSON number, not a string — `42` cannot be a semver range because semver ranges are strings). Run `loopx run -n 1 ralph`. Assert: (a) exit code 0, (b) stderr contains an invalid-semver / `package.json` warning for `ralph` (the same warning class as T-VER-09 — exact phrasing implementation-defined), and (c) the script ran (marker file written). A buggy implementation that pre-coerced non-string values to strings (`String(42) === "42"`) might wrongly attempt to parse `"42"` and emit a different error, or silently coerce and then fail to detect the malformed input — both regressions caught here. The contract from SPEC 3.2 "Valid JSON but `loopx` version field contains an invalid semver range: A warning is printed to stderr" applies to any value that is not a valid semver range, including non-string values. *(Spec 3.2)*
 - **T-VER-10**: `dependencies` range wins over `devDependencies` when both are present. Set up a workflow `package.json` with `dependencies.loopx` having a satisfied range and `devDependencies.loopx` having an unsatisfied range → no version mismatch warning on stderr. Reverse the ranges (`dependencies.loopx` unsatisfied, `devDependencies.loopx` satisfied) → version mismatch warning on stderr, execution continues. *(Spec 3.2)*
 - **T-VER-10a**: Runtime: `dependencies.loopx` has an invalid semver range (e.g., `"not-a-range"`), `devDependencies.loopx` has a valid but unsatisfied range (e.g., `">=999.0.0"`). Assert: (a) stderr contains a warning about the invalid semver range in `dependencies`, (b) stderr does NOT contain a version mismatch warning (the version check is skipped, not failed), and (c) execution continues. The `dependencies` field takes precedence — when it is present but invalid, loopx warns and skips version checking entirely. It must not fall back to `devDependencies.loopx`. *(Spec 3.2)*
 - **T-VER-10b**: Runtime: `dependencies.loopx` has a valid, satisfied range, `devDependencies.loopx` has an invalid semver range (e.g., `"not-a-range"`). Assert: (a) no version mismatch warning on stderr, (b) no invalid-semver warning on stderr, and (c) execution continues normally. When `dependencies.loopx` is present, `devDependencies.loopx` is ignored entirely — it is not read or validated, even if malformed. T-VER-10 proves precedence with two valid ranges; T-VER-10a proves no fallback when `dependencies` is invalid. This test closes the converse gap: `dependencies` is valid and satisfied, so `devDependencies` must be invisible regardless of its content. *(Spec 3.2)*
 - **T-VER-11**: `optionalDependencies` ignored at workflow level. Workflow `package.json` declares `loopx` only in `optionalDependencies` with an unsatisfied range → no version warning at runtime. *(Spec 3.2)*
 - **T-VER-11a**: Runtime: `optionalDependencies.loopx` with an invalid semver range (e.g., `"not-a-range"`) is ignored. Workflow `package.json` declares `loopx` only in `optionalDependencies` with an invalid semver range — no `dependencies.loopx` or `devDependencies.loopx` present. Assert: (a) exit code 0, (b) no version mismatch warning on stderr, and (c) no invalid-semver or `package.json` warning on stderr. T-VER-11 covers a valid-but-unsatisfied `optionalDependencies.loopx`; this extends coverage to the malformed case, proving the field is fully invisible at the workflow level — it is not read or validated, even when malformed. An implementation that read `optionalDependencies.loopx` only to emit invalid-semver warnings would fail this test. *(Spec 3.2)*
-- **T-VER-11b**: Runtime: `peerDependencies.loopx` is ignored at the workflow level. Workflow `package.json` declares `loopx` only in `peerDependencies` with a valid but unsatisfied range (e.g., `">=999.0.0"`) — no `dependencies.loopx`, `devDependencies.loopx`, or `optionalDependencies.loopx` present. Create `.loopx/ralph/index.sh` and run `loopx run -n 1 ralph`. Assert: (a) exit code 0, (b) no version mismatch warning on stderr, and (c) no `package.json`-related warning on stderr. Per SPEC 3.2, workflow-level version checking reads only `dependencies` and `devDependencies` (with `optionalDependencies` explicitly ignored at the workflow level). T-VER-11 / T-VER-11a prove `optionalDependencies` is ignored at runtime; this test proves `peerDependencies` is also outside the checked set — the field is fully invisible at the workflow level and must not trigger a mismatch warning. **Classification:** derived-spec coverage, not core ADR-0003 acceptance coverage. SPEC 3.2 enumerates the workflow-level checked fields explicitly (`dependencies`, `devDependencies`; with `optionalDependencies` explicitly excluded) but does not explicitly discuss `peerDependencies`; this test validates an exclusion that follows from the enumerated-list semantics rather than from a direct ADR-0003 statement. Keep as a useful boundary test, but do not gate ADR-0003 acceptance on it. *(Spec 3.2)*
+- **T-VER-11b**: Runtime: `peerDependencies.loopx` is ignored at the workflow level. Workflow `package.json` declares `loopx` only in `peerDependencies` with a valid but unsatisfied range (e.g., `">=999.0.0"`) — no `dependencies.loopx`, `devDependencies.loopx`, or `optionalDependencies.loopx` present. Create `.loopx/ralph/index.sh` and run `loopx run -n 1 ralph`. Assert: (a) exit code 0, (b) no version mismatch warning on stderr, and (c) no `package.json`-related warning on stderr. Per SPEC 3.2, workflow-level version checking reads only `dependencies` and `devDependencies` (with `optionalDependencies` explicitly ignored at the workflow level), and `peerDependencies` is not one of the enumerated fields, so a `loopx` declaration there is invisible to the workflow-level version check. T-VER-11 / T-VER-11a prove `optionalDependencies` is ignored at runtime; this test closes the gap by proving `peerDependencies` is also outside the checked set. *(Spec 3.2)*
+- **T-VER-11b2**: Runtime: `peerDependencies.loopx` with an **invalid** semver range (e.g., `"not-a-range!!!"`) is ignored at the workflow level. Workflow `package.json` declares `loopx` only in `peerDependencies` with an invalid semver range — no `dependencies.loopx`, `devDependencies.loopx`, or `optionalDependencies.loopx` present. Create `.loopx/ralph/index.sh` and run `loopx run -n 1 ralph`. Assert: (a) exit code 0, (b) no version mismatch warning on stderr, and (c) no invalid-semver or `package.json` warning on stderr. T-VER-11b covers a valid-but-unsatisfied `peerDependencies.loopx`; this extends coverage to the malformed case, proving the field is fully invisible at the workflow level — it is not read or validated, even when malformed. This is the `peerDependencies` counterpart to T-VER-11a (`optionalDependencies` invalid range). An implementation that read `peerDependencies.loopx` only to emit invalid-semver warnings would fail this test. *(Spec 3.2)*
 - **T-VER-11c**: Runtime: `optionalDependencies.loopx` does not rescue an unsatisfied `dependencies.loopx`. Workflow `package.json` declares `loopx` in BOTH `dependencies` (with an unsatisfied range, e.g., `">=999.0.0"`) AND `optionalDependencies` (with a satisfied range, e.g., `"*"` or the running version's exact value) — no `devDependencies.loopx`. Create `.loopx/ralph/index.sh` and run `loopx run -n 1 ralph`. Assert: (a) exit code 0, and (b) stderr contains a version mismatch warning for `ralph`. Because `optionalDependencies` is intentionally not checked at the workflow level (Spec 3.2), its satisfied range must not suppress the `dependencies` mismatch warning. T-VER-11 / T-VER-11a prove `optionalDependencies` alone is ignored at runtime, and T-VER-14a pins down the mixed case for `devDependencies` + `optionalDependencies`; this test closes the symmetric gap for `dependencies` + `optionalDependencies`, covering the highest-precedence workflow-level version-check field (Spec 3.2: `dependencies` wins over `devDependencies`) in the mixed-field configuration. An implementation that wrongly merged `optionalDependencies` into the workflow-level check would suppress the mismatch warning and fail this test. *(Spec 3.2)*
-- **T-VER-12**: Install-time version checking: `dependencies` range wins over `devDependencies` when both are present in a workflow's `package.json`. Set up `dependencies.loopx` with a satisfied range and `devDependencies.loopx` with an unsatisfied range → install succeeds (no version mismatch error). Reverse the ranges → install fails. *(Spec 3.2, 10.6)*
-- **T-VER-12a**: Install-time: `dependencies.loopx` has an invalid semver range, `devDependencies.loopx` has a valid but unsatisfied range. Assert: (a) stderr contains a warning about the invalid semver range in `dependencies`, (b) install succeeds (the version check is skipped, not failed — invalid semver does not block install per Spec 3.2), and (c) no version mismatch error is reported. The `dependencies` field takes precedence — when it is present but invalid, the version check is skipped entirely. It must not fall back to `devDependencies.loopx`. This is the install-time counterpart to T-VER-10a. *(Spec 3.2, 10.6)*
-- **T-VER-12b**: Install-time: `dependencies.loopx` has a valid, satisfied range, `devDependencies.loopx` has an invalid semver range (e.g., `"not-a-range"`). Assert: (a) install succeeds, (b) no invalid-semver warning on stderr, and (c) no version mismatch error. When `dependencies.loopx` is present, `devDependencies.loopx` is ignored entirely at install time — it is not read or validated, even if malformed. This is the install-time counterpart to T-VER-10b. *(Spec 3.2, 10.6)*
-- **T-VER-13**: Install-time version checking: `optionalDependencies.loopx` is ignored at the workflow level. Workflow `package.json` declares `loopx` only in `optionalDependencies` with an unsatisfied range → install succeeds (no version check performed). *(Spec 3.2, 10.6)*
-- **T-VER-13a**: Install-time: `optionalDependencies.loopx` with an invalid semver range (e.g., `"not-a-range"`) is ignored. A workflow source's `package.json` declares `loopx` only in `optionalDependencies` with an invalid semver range — no `dependencies.loopx` or `devDependencies.loopx` present. Run `loopx install <source>`. Assert: (a) exit code 0, (b) the workflow is installed, (c) no version mismatch error, and (d) no invalid-semver or `package.json` warning on stderr. This is the install-time counterpart to T-VER-11a, extending T-VER-13 (valid-but-unsatisfied) to the malformed case. Proves `optionalDependencies.loopx` is fully invisible at the workflow level at install time as well. *(Spec 3.2, 10.6)*
-- **T-VER-13b**: Install-time: `peerDependencies.loopx` is ignored at the workflow level. A workflow source's `package.json` declares `loopx` only in `peerDependencies` with a valid but unsatisfied range (e.g., `">=999.0.0"`) — no `dependencies.loopx`, `devDependencies.loopx`, or `optionalDependencies.loopx` present. Run `loopx install <source>`. Assert: (a) exit code 0, (b) the workflow is installed, (c) no version mismatch error, and (d) no `package.json`-related warning on stderr. Per SPEC 3.2, install-time version checking uses the same rules as runtime — only `dependencies` and `devDependencies` are read. T-VER-13 / T-VER-13a prove `optionalDependencies` is ignored at install time; this is the `peerDependencies` counterpart and the install-time mirror of T-VER-11b, locking down that the excluded-dependency-field set is the same at install time as at runtime. **Classification:** derived-spec coverage, not core ADR-0003 acceptance coverage. SPEC 3.2 enumerates the workflow-level checked fields explicitly (`dependencies`, `devDependencies`; with `optionalDependencies` explicitly excluded) but does not explicitly discuss `peerDependencies`; this test validates an exclusion that follows from the enumerated-list semantics rather than from a direct ADR-0003 statement. Keep as a useful boundary test, but do not gate ADR-0003 acceptance on it. *(Spec 3.2, 10.6)*
-- **T-VER-13c**: Install-time: `optionalDependencies.loopx` does not rescue an unsatisfied `dependencies.loopx`. Workflow source's `package.json` declares `loopx` in BOTH `dependencies` (with an unsatisfied range, e.g., `">=999.0.0"`) AND `optionalDependencies` (with a satisfied range, e.g., `"*"` or the running version's exact value) — no `devDependencies.loopx`. Run `loopx install <source>`. Assert: (a) exit code 1 with a version mismatch error, and (b) the workflow is not installed. With `-y`, the install succeeds (override). This is the install-time counterpart to T-VER-11c — the "ignore `optionalDependencies` at the workflow level" rule applies identically at install time (Spec 3.2 and 10.6), and a satisfied `optionalDependencies.loopx` must not suppress the install-blocking mismatch detected via `dependencies.loopx`. T-VER-13 / T-VER-13a prove `optionalDependencies` alone is ignored at install time, and T-VER-15a pins down the mixed case for `devDependencies` + `optionalDependencies` at install time; this test closes the symmetric gap for `dependencies` + `optionalDependencies` at install time, covering the highest-precedence workflow-level version-check field (Spec 3.2: `dependencies` wins over `devDependencies`) in the mixed-field configuration. *(Spec 3.2, 10.6)*
+- **T-VER-11d**: Runtime: invalid semver in a non-`loopx` dependency field is completely ignored. SPEC 3.2 only validates the `loopx` entries in `dependencies` and `devDependencies`; other dependency entries (including entries with invalid semver ranges) are outside loopx's concern. Create `.loopx/ralph/index.sh` and `.loopx/ralph/package.json` containing `{ "dependencies": { "not-loopx": "not-a-range!!!" } }` (no `loopx` field anywhere — the invalid range is on a non-`loopx` dependency). Run `loopx run -n 1 ralph`. Assert: (a) exit code 0, (b) stderr contains no `package.json`-related warnings (no invalid-semver warning, no parse warning, no version-mismatch warning), and (c) the workflow runs normally. An implementation that walks every `dependencies.*` entry looking for invalid semver ranges — rather than reading only `dependencies.loopx` — would wrongly emit a warning here. *(Spec 3.2)*
+- **T-VER-12**: Install-time version checking: `dependencies` range wins over `devDependencies` when both are present in a workflow's `package.json`. Set up `dependencies.loopx` with a satisfied range and `devDependencies.loopx` with an unsatisfied range → install succeeds (no version mismatch error). Reverse the ranges → install fails. **The satisfied-range sub-case (the install-succeeds branch) must pass `--no-install` per the section 4.10 suite-wide auto-install-awareness rule** — the source workflow has a top-level `package.json` and the install commits, which would trigger the SPEC 10.10 post-commit auto-install pass; this test's contract is the precedence rule, not auto-install. The reverse-ranges sub-case (install fails before commit on version mismatch) does not need `--no-install` because no commit means no auto-install candidate. *(Spec 3.2, 10.6)*
+- **T-VER-12a**: Install-time: `dependencies.loopx` has an invalid semver range, `devDependencies.loopx` has a valid but unsatisfied range. Run `loopx install --no-install <source>`. Assert: (a) stderr contains a warning about the invalid semver range in `dependencies`, (b) install succeeds (the version check is skipped, not failed — invalid semver does not block install per Spec 3.2), and (c) no version mismatch error is reported. The `dependencies` field takes precedence — when it is present but invalid, the version check is skipped entirely. It must not fall back to `devDependencies.loopx`. This is the install-time counterpart to T-VER-10a. **`--no-install` per the section 4.10 suite-wide auto-install-awareness rule** — the source workflow's top-level `package.json` would otherwise drive the post-commit auto-install pass, which is incidental to this test's contract (precedence rule with invalid `dependencies`). *(Spec 3.2, 10.6)*
+- **T-VER-12b**: Install-time: `dependencies.loopx` has a valid, satisfied range, `devDependencies.loopx` has an invalid semver range (e.g., `"not-a-range"`). Run `loopx install --no-install <source>`. Assert: (a) install succeeds, (b) no invalid-semver warning on stderr, and (c) no version mismatch error. When `dependencies.loopx` is present, `devDependencies.loopx` is ignored entirely at install time — it is not read or validated, even if malformed. This is the install-time counterpart to T-VER-10b. **`--no-install` per the section 4.10 suite-wide auto-install-awareness rule** — the source workflow's top-level `package.json` (with a satisfied `dependencies.loopx`) would otherwise drive the post-commit auto-install pass, which is incidental to this test's contract (the `dependencies`-takes-precedence-and-`devDependencies`-is-ignored rule). *(Spec 3.2, 10.6)*
+- **T-VER-12c**: Install-time: workflow source's `package.json` `loopx` field is a **non-string** value → invalid-semver warning, install proceeds without a version mismatch error. Install-time counterpart to T-VER-09a (runtime). Source's `package.json` contains `{ "dependencies": { "loopx": 42 } }` (JSON number, not a string). Run `loopx install --no-install <source>`. Assert: (a) exit code 0 — invalid-semver warnings are non-fatal at install time per SPEC 3.2 (only valid-but-unsatisfied ranges block install), (b) stderr contains an invalid-semver / `package.json` warning for the workflow (same warning class as T-VER-12a's invalid-string variant), (c) no version mismatch error is reported, and (d) the workflow is committed at `.loopx/<name>/`. A buggy implementation that coerced `42` to `"42"` and treated it as a satisfied range (because `42` would parse loosely as `>=42.0.0` if any pre-coercion happened) could pass T-VER-09 / T-VER-12a — this test pins down that non-string values are also treated as malformed, not silently coerced. **`--no-install` per the section 4.10 suite-wide auto-install-awareness rule** — the source workflow has a top-level `package.json` and the install commits, which would otherwise trigger the SPEC 10.10 post-commit auto-install pass; this test's contract is the non-string-loopx-warning behavior, not auto-install. (Per SPEC 10.10, malformed `package.json` would actually skip auto-install — but the test does not need to assert that: T-VER-15c covers the malformed-`package.json`-skip-auto-install contract explicitly with `withFakeNpm`. Using `--no-install` here keeps this test's contract narrow.) *(Spec 3.2, 10.6)*
+- **T-VER-13**: Install-time version checking: `optionalDependencies.loopx` is ignored at the workflow level. Workflow `package.json` declares `loopx` only in `optionalDependencies` with an unsatisfied range → install succeeds (no version check performed). Run `loopx install --no-install <source>`. **`--no-install` per the section 4.10 suite-wide auto-install-awareness rule** — the source workflow has a top-level `package.json` and the install commits, which would otherwise trigger the SPEC 10.10 post-commit auto-install pass; this test's contract is the `optionalDependencies`-is-ignored rule, not auto-install. *(Spec 3.2, 10.6)*
+- **T-VER-13a**: Install-time: `optionalDependencies.loopx` with an invalid semver range (e.g., `"not-a-range"`) is ignored. A workflow source's `package.json` declares `loopx` only in `optionalDependencies` with an invalid semver range — no `dependencies.loopx` or `devDependencies.loopx` present. Run `loopx install --no-install <source>`. Assert: (a) exit code 0, (b) the workflow is installed, (c) no version mismatch error, and (d) no invalid-semver or `package.json` warning on stderr. This is the install-time counterpart to T-VER-11a, extending T-VER-13 (valid-but-unsatisfied) to the malformed case. Proves `optionalDependencies.loopx` is fully invisible at the workflow level at install time as well. **`--no-install` per the section 4.10 suite-wide auto-install-awareness rule** — the source workflow has a top-level `package.json` and the install commits; auto-install is incidental to this test's contract. *(Spec 3.2, 10.6)*
+- **T-VER-13b**: Install-time: `peerDependencies.loopx` is ignored at the workflow level. A workflow source's `package.json` declares `loopx` only in `peerDependencies` with a valid but unsatisfied range (e.g., `">=999.0.0"`) — no `dependencies.loopx`, `devDependencies.loopx`, or `optionalDependencies.loopx` present. Run `loopx install --no-install <source>`. Assert: (a) exit code 0, (b) the workflow is installed, (c) no version mismatch error, and (d) no `package.json`-related warning on stderr. Per SPEC 3.2, install-time version checking uses the same rules as runtime — only `dependencies` and `devDependencies` are read, and `peerDependencies` is not one of the enumerated fields. T-VER-13 / T-VER-13a prove `optionalDependencies` is ignored at install time; this is the `peerDependencies` counterpart and the install-time mirror of T-VER-11b, locking down that the excluded-dependency-field set is the same at install time as at runtime. **`--no-install` per the section 4.10 suite-wide auto-install-awareness rule** — the source workflow has a top-level `package.json` and the install commits; auto-install is incidental to this test's contract. *(Spec 3.2, 10.6)*
+- **T-VER-13b2**: Install-time: `peerDependencies.loopx` with an **invalid** semver range (e.g., `"not-a-range!!!"`) is ignored at the workflow level. A workflow source's `package.json` declares `loopx` only in `peerDependencies` with an invalid semver range — no `dependencies.loopx`, `devDependencies.loopx`, or `optionalDependencies.loopx` present. Run `loopx install --no-install <source>`. Assert: (a) exit code 0, (b) the workflow is installed, (c) no version mismatch error, and (d) no invalid-semver or `package.json` warning on stderr. This is the install-time counterpart to T-VER-11b2 and the `peerDependencies` mirror of T-VER-13a (`optionalDependencies` invalid range at install time). Proves `peerDependencies.loopx` is fully invisible at the workflow level at install time as well — it is not read or validated, even when malformed. **`--no-install` per the section 4.10 suite-wide auto-install-awareness rule** — the source workflow has a top-level `package.json` and the install commits; auto-install is incidental to this test's contract. *(Spec 3.2, 10.6)*
+- **T-VER-13c**: Install-time: `optionalDependencies.loopx` does not rescue an unsatisfied `dependencies.loopx`. Workflow source's `package.json` declares `loopx` in BOTH `dependencies` (with an unsatisfied range, e.g., `">=999.0.0"`) AND `optionalDependencies` (with a satisfied range, e.g., `"*"` or the running version's exact value) — no `devDependencies.loopx`. Run `loopx install <source>`. Assert: (a) exit code 1 with a version mismatch error, and (b) the workflow is not installed. With `-y`, the install succeeds (override). **The blocking-preflight sub-case (no `-y`) does not need `--no-install`** because no commit means no auto-install candidate (per the section 4.10 suite-wide rule's "blocking-preflight" carve-out). **The `-y` success sub-case must pass `--no-install`** (i.e., run `loopx install -y --no-install <source>`) per the section 4.10 suite-wide auto-install-awareness rule — `-y` unblocks preflight and the install commits, which would otherwise drive the SPEC 10.10 post-commit auto-install pass; this test's contract is the `-y`-overrides-mismatch behavior, not the auto-install combination (T-INST-120b covers `-y` × auto-install with `withFakeNpm` separately). This is the install-time counterpart to T-VER-11c — the "ignore `optionalDependencies` at the workflow level" rule applies identically at install time (Spec 3.2 and 10.6), and a satisfied `optionalDependencies.loopx` must not suppress the install-blocking mismatch detected via `dependencies.loopx`. T-VER-13 / T-VER-13a prove `optionalDependencies` alone is ignored at install time, and T-VER-15a pins down the mixed case for `devDependencies` + `optionalDependencies` at install time; this test closes the symmetric gap for `dependencies` + `optionalDependencies` at install time, covering the highest-precedence workflow-level version-check field (Spec 3.2: `dependencies` wins over `devDependencies`) in the mixed-field configuration. *(Spec 3.2, 10.6)*
+- **T-VER-13d**: Install-time: invalid semver in a non-`loopx` dependency field is completely ignored. Install-time counterpart to T-VER-11d. Prepare a single-workflow source with `index.sh` and a `package.json` containing `{ "dependencies": { "not-loopx": "not-a-range!!!" } }` (no `loopx` field anywhere). Run `loopx install --no-install <source>`. Assert: (a) exit code 0, (b) stderr contains no `package.json`-related warnings (no invalid-semver warning, no parse warning, no version-mismatch error), and (c) the workflow is installed at `.loopx/<name>/` with its `package.json` preserved byte-for-byte. Because SPEC 3.2 restricts version validation to `dependencies.loopx` and `devDependencies.loopx`, an invalid semver range on an unrelated dependency field must not produce a warning or block install. **`--no-install` per the section 4.10 suite-wide auto-install-awareness rule** — the source workflow has a top-level `package.json` and the install commits; auto-install is incidental to this test's contract (the non-`loopx`-field-is-ignored rule). *(Spec 3.2, 10.6)*
 - **T-VER-14**: Runtime version checking: `devDependencies.loopx` only (no `dependencies.loopx`). Workflow `package.json` declares `loopx` only in `devDependencies` with an unsatisfied range → warning on stderr, execution continues. This proves the `devDependencies`-only path works independently of the `dependencies`-over-`devDependencies` precedence rule tested in T-VER-10. *(Spec 3.2)*
 - **T-VER-14a**: Runtime: `optionalDependencies.loopx` does not rescue an unsatisfied `devDependencies.loopx`. Workflow `package.json` declares `loopx` in BOTH `devDependencies` (with an unsatisfied range, e.g., `">=999.0.0"`) AND `optionalDependencies` (with a satisfied range, e.g., `"*"` or the running version's exact value) — no `dependencies.loopx`. Create `.loopx/ralph/index.sh` and run `loopx run -n 1 ralph`. Assert: (a) exit code 0, and (b) stderr contains a version mismatch warning for `ralph`. Because `optionalDependencies` is intentionally not checked at the workflow level (Spec 3.2), its satisfied range must not suppress the `devDependencies` mismatch warning. T-VER-11 / T-VER-11a prove `optionalDependencies` alone is ignored, and T-VER-14 proves `devDependencies`-only unsatisfied warns; this test pins down the mixed case where a satisfied `optionalDependencies` could appear to "rescue" the check if an implementation wrongly merged fields. *(Spec 3.2)*
+- **T-VER-14b**: Runtime: `devDependencies.loopx` only with a **satisfied** range — no warning, execution continues. Companion to T-VER-14 (which pins down the unsatisfied-range branch). Workflow `package.json` declares `loopx` only in `devDependencies` with a satisfied range (e.g., `"*"` or the running version's exact value) — no `dependencies.loopx`, no `optionalDependencies.loopx`, no `peerDependencies.loopx`. Create `.loopx/ralph/index.sh` and run `loopx run -n 1 ralph`. Assert: (a) exit code 0, (b) stderr contains **no** version-related warnings, and (c) the workflow runs normally (script marker file written). T-VER-10 covers the satisfied-`devDependencies` case only when `dependencies.loopx` is also present (precedence context); this test closes the standalone `devDependencies`-only-satisfied gap. A buggy implementation that skipped reading `devDependencies.loopx` unless `dependencies.loopx` was also declared would still pass existing tests but fail here if it then incorrectly warned about a "missing" range. *(Spec 3.2)*
+- **T-VER-14c**: Runtime: `devDependencies.loopx` only with an **invalid** semver range — invalid-semver warning, execution continues. Companion to T-VER-14 (unsatisfied) and T-VER-14b (satisfied). Workflow `package.json` declares `loopx` only in `devDependencies` with an invalid semver range (e.g., `"not-a-range!!!"`) — no `dependencies.loopx`. Create `.loopx/ralph/index.sh` and run `loopx run -n 1 ralph`. Assert: (a) exit code 0, (b) stderr contains exactly one invalid-semver warning for the `devDependencies.loopx` range in `ralph/package.json`, and (c) the workflow runs normally. T-VER-10a/10b cover invalid-semver on `devDependencies` only in precedence-mixed scenarios (where `dependencies` is also present); this test closes the standalone `devDependencies`-only-invalid gap. *(Spec 3.2)*
+- **T-VER-14d**: Runtime: `devDependencies.loopx` only with a **non-string** value — invalid-semver warning, execution continues. Companion to T-VER-14c (invalid-string range), parity with T-VER-09a (non-string `dependencies.loopx`). T-VER-09a covers the non-string-type path on `dependencies.loopx`; this test extends parity to `devDependencies.loopx` because SPEC 3.2 names both as workflow-level checked fields and the "valid JSON but `loopx` version field contains an invalid semver range" rule applies symmetrically across them. Create `.loopx/ralph/index.sh` and `.loopx/ralph/package.json` containing `{ "devDependencies": { "loopx": 42 } }` (a JSON number, not a string — `42` cannot be a semver range because semver ranges are strings) — no `dependencies.loopx`, no `optionalDependencies.loopx`. Run `loopx run -n 1 ralph`. Assert: (a) exit code 0, (b) stderr contains an invalid-semver / `package.json` warning for `ralph` (same warning class as T-VER-14c — exact phrasing implementation-defined), and (c) the script ran (marker file written). A buggy implementation that pre-coerced non-string values to strings (`String(42) === "42"`) might wrongly attempt to parse `"42"` as a satisfied range, or could silently coerce and skip the warning entirely; either regression is caught here. *(Spec 3.2)*
 - **T-VER-15**: Install-time version checking: `devDependencies.loopx` only (no `dependencies.loopx`). Workflow `package.json` declares `loopx` only in `devDependencies` with an unsatisfied range → install refused with version mismatch error. This proves the `devDependencies`-only install path works independently of the precedence rule tested in T-VER-12. *(Spec 3.2, 10.6)*
-- **T-VER-15a**: Install-time: `optionalDependencies.loopx` does not rescue an unsatisfied `devDependencies.loopx`. Workflow source's `package.json` declares `loopx` in BOTH `devDependencies` (with an unsatisfied range, e.g., `">=999.0.0"`) AND `optionalDependencies` (with a satisfied range, e.g., `"*"` or the running version's exact value) — no `dependencies.loopx`. Run `loopx install <source>`. Assert: (a) exit code 1 with a version mismatch error, and (b) the workflow is not installed. With `-y`, the install succeeds (override). This is the install-time counterpart to T-VER-14a — the "ignore `optionalDependencies` at the workflow level" rule applies identically at install time (Spec 3.2 and 10.6), and a satisfied `optionalDependencies.loopx` must not suppress the install-blocking mismatch detected via `devDependencies.loopx`. T-VER-13 / T-VER-13a prove `optionalDependencies` alone is ignored at install time, and T-VER-15 proves `devDependencies`-only unsatisfied blocks install; this test pins down the mixed case. *(Spec 3.2, 10.6)*
+- **T-VER-15b**: Install-time: `devDependencies.loopx` only with a **satisfied** range — install succeeds, no warning. Companion to T-VER-15 (unsatisfied). Workflow source's `package.json` declares `loopx` only in `devDependencies` with a satisfied range (e.g., `"*"` or the running version's exact value) — no `dependencies.loopx`, no `optionalDependencies.loopx`. Run `loopx install --no-install <source>`. Assert: (a) exit code 0, (b) the workflow is installed at `.loopx/<name>/`, (c) stderr contains no version-related warnings or errors. This is the install-time counterpart to T-VER-14b; closes the standalone `devDependencies`-only-satisfied gap at install time. **`--no-install` per the section 4.10 suite-wide auto-install-awareness rule** — the source workflow has a top-level `package.json` (with a satisfied `devDependencies.loopx`) and the install commits; auto-install is incidental to this test's contract. *(Spec 3.2, 10.6)*
+- **T-VER-15c**: Install-time: `devDependencies.loopx` only with an **invalid** semver range — warning, install succeeds, auto-install skips per malformed-`package.json` rules. Companion to T-VER-15 (unsatisfied) and T-VER-15b (satisfied). Workflow source's `package.json` declares `loopx` only in `devDependencies` with an invalid semver range (e.g., `"not-a-range!!!"`) — no `dependencies.loopx`, no `optionalDependencies.loopx`. Use `withFakeNpm({ exitCode: 0, logFile })`. Run `loopx install <source>`. Assert: (a) exit code 0 — invalid semver does not block install per Spec 3.2 (install succeeds even with a `package.json` parse/validation warning), (b) the workflow is installed at `.loopx/<name>/`, (c) stderr contains exactly one invalid-semver warning for the `devDependencies.loopx` range, (d) per SPEC 10.10 "Malformed `package.json`" rules, auto-install **skips** this workflow (the fake-npm shim log is empty — `npm install` is not invoked), and (e) no `.gitignore` synthesis occurred (the safeguard runs under the same trigger conditions as `npm install`). This is the install-time counterpart to T-VER-14c. An implementation that validated `devDependencies.loopx` only when `dependencies.loopx` is also present would miss this warning path; conversely an implementation that treated the invalid-semver warning as a fatal install error would incorrectly block install. *(Spec 3.2, 10.6, 10.10)*
+- **T-VER-15d**: Install-time: `devDependencies.loopx` only with a **non-string** value — warning, install succeeds, auto-install skips per malformed-`package.json` rules. Install-time companion to T-VER-14d (runtime non-string `devDependencies.loopx`); parity with T-VER-12c (install-time non-string `dependencies.loopx`). SPEC 3.2's "valid JSON but `loopx` version field contains an invalid semver range" rule applies symmetrically across `dependencies.loopx` and `devDependencies.loopx`, and SPEC 10.10's "Malformed `package.json`" auto-install-skip behavior applies whenever the workflow's `package.json` is unreadable / invalid JSON / unparseable for the loopx version range — the non-string-`loopx`-value case falls under "unparseable" because the value cannot be a semver range. Workflow source's `package.json` contains `{ "devDependencies": { "loopx": 42 } }` (JSON number, not a string) — no `dependencies.loopx`, no `optionalDependencies.loopx`. Use `withFakeNpm({ exitCode: 0, logFile })`. Run `loopx install <source>`. Assert: (a) exit code 0 — invalid semver does not block install per SPEC 3.2 (install succeeds even with a `package.json` warning), (b) the workflow is installed at `.loopx/<name>/`, (c) stderr contains an invalid-semver / `package.json` warning for the `devDependencies.loopx` non-string value (same warning class as T-VER-15c — exact phrasing implementation-defined), (d) per SPEC 10.10 "Malformed `package.json`" rules, auto-install **skips** this workflow (the fake-npm shim log is empty — `npm install` is not invoked), and (e) no `.gitignore` synthesis occurred. A buggy implementation that pre-coerced `42` to `"42"` and treated it as a satisfied range could pass T-VER-12c's exit-code assertion (which is 0) while wrongly invoking auto-install (because the pre-coerced value would be a "valid" semver under loose parsing); this test catches that regression by asserting the auto-install skip on the shim log. **Uses `withFakeNpm` not `--no-install`** because the auto-install-skip assertion is the central contract — the shim's empty log is the assertion surface. *(Spec 3.2, 10.6, 10.10)*
+- **T-VER-15a**: Install-time: `optionalDependencies.loopx` does not rescue an unsatisfied `devDependencies.loopx`. Workflow source's `package.json` declares `loopx` in BOTH `devDependencies` (with an unsatisfied range, e.g., `">=999.0.0"`) AND `optionalDependencies` (with a satisfied range, e.g., `"*"` or the running version's exact value) — no `dependencies.loopx`. Run `loopx install <source>`. Assert: (a) exit code 1 with a version mismatch error, and (b) the workflow is not installed. With `-y`, the install succeeds (override). **The blocking-preflight sub-case (no `-y`) does not need `--no-install`** because no commit means no auto-install candidate (per the section 4.10 suite-wide rule's "blocking-preflight" carve-out). **The `-y` success sub-case must pass `--no-install`** (i.e., run `loopx install -y --no-install <source>`) per the section 4.10 suite-wide auto-install-awareness rule — `-y` unblocks preflight and the install commits, which would otherwise drive the SPEC 10.10 post-commit auto-install pass; T-INST-120b covers `-y` × auto-install with `withFakeNpm` separately. This is the install-time counterpart to T-VER-14a — the "ignore `optionalDependencies` at the workflow level" rule applies identically at install time (Spec 3.2 and 10.6), and a satisfied `optionalDependencies.loopx` must not suppress the install-blocking mismatch detected via `devDependencies.loopx`. T-VER-13 / T-VER-13a prove `optionalDependencies` alone is ignored at install time, and T-VER-15 proves `devDependencies`-only unsatisfied blocks install; this test pins down the mixed case. *(Spec 3.2, 10.6)*
 - **T-VER-16**: Runtime: workflow has a valid `package.json` with no `loopx` declared in any dependency field (e.g., `{ "name": "my-workflow", "version": "1.0.0" }`) → no version check is performed, no warning emitted. Execution proceeds normally. This explicitly tests the "valid JSON, no `loopx` dependency declared → no version check" rule from Spec 3.2. *(Spec 3.2)*
-- **T-VER-17**: Install-time: workflow source has a valid `package.json` with no `loopx` declared in any dependency field → no version check is performed, install succeeds without version-related errors or warnings. *(Spec 3.2, 10.6)*
+- **T-VER-17**: Install-time: workflow source has a valid `package.json` with no `loopx` declared in any dependency field → no version check is performed, install succeeds without version-related errors or warnings. Run `loopx install --no-install <source>`. **`--no-install` per the section 4.10 suite-wide auto-install-awareness rule** — the source workflow has a top-level `package.json` and the install commits, which would otherwise trigger the SPEC 10.10 post-commit auto-install pass; this test's contract is the no-`loopx`-declared / no-version-check rule, not auto-install. *(Spec 3.2, 10.6)*
 - **T-VER-18**: Unentered sibling workflows are not version-checked. Create `.loopx/good/index.sh` (the starting workflow, no `package.json`) and `.loopx/sibling/index.sh` with a `package.json` declaring a loopx range NOT satisfied by the running version. Run `loopx run -n 1 good` (the starting workflow completes without ever entering `sibling`). Assert: (a) exit code 0, and (b) no version mismatch warning on stderr for `sibling`. Version checks are entry-scoped — only workflows actually entered during the loop have their `package.json` checked. *(Spec 3.2)*
 - **T-VER-18a**: Unentered sibling workflow with broken `package.json` emits no warning. Create `.loopx/good/index.sh` (the starting workflow, no `package.json`) and `.loopx/sibling/index.sh` with a `package.json` containing invalid JSON (e.g., `{{{INVALID`). Run `loopx run -n 1 good`. Assert: (a) exit code 0, and (b) stderr contains no `package.json`-related warnings (no JSON parse warning, no version warning). T-VER-18 covers an unentered sibling with an unsatisfied range; this test extends coverage to the `package.json` failure-warning path (invalid JSON), proving that `package.json` failure warnings are also entry-scoped — the sibling's `package.json` is never read because the sibling workflow is never entered. *(Spec 3.2)*
 - **T-VER-19**: `loopx run -h` does not perform workflow version or `package.json` checks. Create `.loopx/ralph/index.sh` with a `package.json` declaring a loopx range NOT satisfied by the running version. Run `loopx run -h`. Assert: (a) help output is displayed, (b) exit code 0, and (c) stderr contains no version mismatch warnings. Version checking is entry-scoped — `run -h` performs discovery and validation (names, collisions) but does not enter any workflow, so version checks do not run. *(Spec 3.2, 11.2)*
@@ -1689,7 +3386,7 @@ The "global" binary is the primary build. The "local" binary is a separate build
 - **T-VER-24c**: No `package.json` failure warning when an explicit `workflow:script` start target names a missing script — broken JSON variant. Same setup as T-VER-24b but `.loopx/ralph/package.json` contains `{{{INVALID` (broken JSON) instead of an unsatisfied range. Run `loopx run ralph:missing`. Assert: (a) exit code 1 with missing-script error for `missing` in `ralph`, and (b) stderr contains no JSON parse warnings for `ralph`. This extends T-VER-24b from the unsatisfied-range path to the invalid-JSON `package.json` failure path, mirroring the T-VER-24 → T-VER-24a split for the bare-target missing-default-entry case and the T-VER-25 → T-VER-25a split for the goto-target-missing-script case. *(Spec 7.1, 3.2, 4.1)*
 - **T-VER-24d**: No version/package warning when an explicit `:index` start target names a non-existent `index` in a workflow without one — unsatisfied range variant. Create `.loopx/ralph/check.sh` (valid workflow with no `index.*` script) and `.loopx/ralph/package.json` containing `{ "dependencies": { "loopx": ">=999.0.0" } }` (an unsatisfied range). Run `loopx run ralph:index`. Assert: (a) exit code 1 with an error about the missing script `index` in workflow `ralph`, and (b) stderr contains no version mismatch or `package.json`-related warnings for `ralph`. Target resolution fails before workflow-entry version checking runs — the workflow is never entered, so its `package.json` is never read. This is the **combined** case that T-VER-24 (bare target, missing default entry), T-VER-24b (explicit `workflow:missing` target), and T-CLI-109a / T-API-20j2 / T-API-45a (plain error shape for `workflow:index` with no index) do not jointly cover: the explicit `:index` target on a workflow that has no index AND a workflow-level version declaration. ADR-0003 makes `index` special only when the script portion is omitted, so the explicit `:index` path must enforce the same "target resolution precedes version checking" ordering as any other missing script. *(Spec 7.1, 3.2, 4.1)*
 - **T-VER-24e**: No `package.json` failure warning when an explicit `:index` start target names a non-existent `index` in a workflow without one — broken JSON variant. Same setup as T-VER-24d but `.loopx/ralph/package.json` contains `{{{INVALID` (broken JSON) instead of an unsatisfied range. Run `loopx run ralph:index`. Assert: (a) exit code 1 with an error about the missing script `index` in workflow `ralph`, and (b) stderr contains no JSON parse warnings for `ralph`. This extends T-VER-24d from the unsatisfied-range path to the invalid-JSON `package.json` failure path, mirroring the T-VER-24 → T-VER-24a and T-VER-24b → T-VER-24c splits. Together T-VER-24d/24e close the combined-case gap across both `package.json` failure branches for the explicit-`:index`-on-no-index-workflow path. *(Spec 7.1, 3.2, 4.1)*
-- **T-VER-25**: No version/package warning when a goto target script does not exist. Create `.loopx/start/index.sh` that outputs `{ "goto": "other:missing" }`. Create `.loopx/other/index.sh` (valid workflow) with `.loopx/other/package.json` containing `{ "dependencies": { "loopx": ">=999.0.0" } }` (an unsatisfied range). Run `loopx run -n 2 start`. Assert: (a) exit code 1 with an error about missing script `missing` in workflow `other`, and (b) stderr contains no version mismatch or `package.json`-related warnings for `other`. Goto target resolution (Spec 7.1 step 11.d) fails before the first-entry version check (step 11.e) — the target workflow is never entered, so its `package.json` is never read. *(Spec 7.1, 3.2)*
+- **T-VER-25**: No version/package warning when a goto target script does not exist. Create `.loopx/start/index.sh` that outputs `{ "goto": "other:missing" }`. Create `.loopx/other/index.sh` (valid workflow) with `.loopx/other/package.json` containing `{ "dependencies": { "loopx": ">=999.0.0" } }` (an unsatisfied range). Run `loopx run -n 2 start`. Assert: (a) exit code 1 with an error about missing script `missing` in workflow `other`, and (b) stderr contains no version mismatch or `package.json`-related warnings for `other`. Goto target resolution (Spec 7.1 step 12.d) fails before the first-entry version check (step 12.e) — the target workflow is never entered, so its `package.json` is never read. *(Spec 7.1, 3.2)*
 - **T-VER-25a**: No `package.json` failure warning when a goto target script does not exist — broken JSON variant. Same setup as T-VER-25 but `.loopx/other/package.json` contains `{{{INVALID` instead of an unsatisfied range. Assert: (a) exit code 1 with missing-script error, and (b) no JSON parse warnings on stderr for `other`. *(Spec 7.1, 3.2)*
 - **T-VER-25b**: No version/package warning when a goto emits `workflow:index` but the target workflow has no `index` — unsatisfied range variant. Create `.loopx/start/index.sh` that outputs `{ "goto": "other:index" }`. Create `.loopx/other/check.sh` (valid workflow with no `index.*` script) and `.loopx/other/package.json` containing `{ "dependencies": { "loopx": ">=999.0.0" } }` (an unsatisfied range). Run `loopx run -n 2 start`. Assert: (a) exit code 1 with an error about the missing script `index` in workflow `other`, and (b) stderr contains no version mismatch or `package.json`-related warnings for `other`. Goto target resolution fails before the first-entry version check — the target workflow is never entered, so its `package.json` is never read. This is the **combined** case that T-LOOP-31c (generic missing `other:index` goto error shape) and T-VER-25 / T-VER-25a (generic missing goto script `other:missing` with unsatisfied range / broken JSON) do not jointly cover: the specific `:index` goto target on a workflow that has no index AND a workflow-level version declaration. ADR-0003 makes `index` special only when the script portion is omitted, and that rule must hold on the cross-workflow goto path as well — so the qualified `workflow:index` goto target into a no-index workflow must follow the ordinary missing-script ordering rule, never entering the workflow and never emitting version/package warnings for it. *(Spec 7.1, 3.2, 2.2, 4.1)*
 - **T-VER-25c**: No `package.json` failure warning when a goto emits `workflow:index` but the target workflow has no `index` — broken JSON variant. Same setup as T-VER-25b but `.loopx/other/package.json` contains `{{{INVALID` (broken JSON) instead of an unsatisfied range. Run `loopx run -n 2 start`. Assert: (a) exit code 1 with an error about the missing script `index` in workflow `other`, and (b) stderr contains no JSON parse warnings for `other`. This extends T-VER-25b from the unsatisfied-range path to the invalid-JSON `package.json` failure path, mirroring the T-VER-25 → T-VER-25a split. Together T-VER-25b/25c close the combined-case gap across both `package.json` failure branches for the goto-`workflow:index`-into-no-index-workflow path. *(Spec 7.1, 3.2, 2.2, 4.1)*
@@ -1796,6 +3493,8 @@ Test the source classification logic (section 10.1) in isolation:
 - URLs that would be single-file → throws (single-file URL install removed)
 - Edge cases: URLs with ports, auth, paths, query strings
 
+**Do not over-pin query-string / fragment URL normalization.** SPEC 10.1 pins source classification by **pathname** (e.g., a pathname ending in `.tar.gz` → tarball; a known-host git URL like `github.com/org/repo` → git) — it does not normatively specify whether query strings (`?x=1`) or URL fragments (`#frag`) on a known-host git URL are retained as-is or stripped before the effective `git clone` URL is constructed. The E2E install tests correctly avoid asserting the exact clone-URL spelling for these cases; source-detection unit tests should do likewise. For inputs such as `https://github.com/org/repo?x=1` or `https://github.com/org/repo#frag`, assert only the classification outcome (e.g., `source.type === "git"`) and not the exact returned URL spelling — unless the implementation deliberately defines `classifySource()` query-string / fragment normalization as an internal test seam with an explicit contract, in which case those contract details can be pinned here.
+
 ### 6.4 Compile-Time Type Tests
 
 **File:** `tests/unit/types.test.ts`
@@ -1804,19 +3503,20 @@ Test the source classification logic (section 10.1) in isolation:
 
 - **T-TYPE-01**: `import type { Output, RunOptions } from "loopx"` compiles without error. *(Spec 9.5)*
 - **T-TYPE-02**: `Output` has optional `result?: string`, `goto?: string`, `stop?: boolean` fields. *(Spec 9.5)*
-- **T-TYPE-03**: `RunOptions` has optional `maxIterations?: number`, `envFile?: string`, `signal?: AbortSignal`, `cwd?: string` fields. *(Spec 9.5)*
+- **T-TYPE-03**: `RunOptions` has optional `maxIterations?: number`, `envFile?: string`, `signal?: AbortSignal`, `cwd?: string`, and `env?: Record<string, string>` fields. Assert that `RunOptions` shape matches the Spec 9.5 definition exactly: each field is optional and has the specified type. A `RunOptions` value with only `env: { FOO: "bar" }` must type-check; a value with `env: { FOO: 42 }` must be a static type error (value is not a string); a value with `env: "not-an-object"` must be a static type error. *(Spec 9.5)*
 - **T-TYPE-04**: `run()` returns `AsyncGenerator<Output>`. *(Spec 9.1, 9.5)*
 - **T-TYPE-05**: `runPromise()` returns `Promise<Output[]>`. *(Spec 9.2, 9.5)*
 - **T-TYPE-06**: `run()` and `runPromise()` accept an optional `RunOptions` second argument. *(Spec 9.1, 9.2, 9.5)*
 - **T-TYPE-07**: `run()` and `runPromise()` require `target` as the first argument (`string`). Omitting `target` is a static type error. *(Spec 9.1, 9.2, 9.5)*
+- **T-TYPE-08**: `import { output, input } from "loopx"` type-checks and exposes the expected script-helper signatures. SPEC 6.4 / 6.5 / 9.4 define `output()` and `input()` as script-side helpers that are part of the public `loopx` module surface; existing type tests pin down only `Output`, `RunOptions`, `run`, and `runPromise`. This test closes the script-helper type-surface gap. Assertions: (a) `import { output, input } from "loopx"` (value import, not `import type`) compiles without error — both helpers are runtime-callable values exported from the package. (b) `input()` has type `Promise<string>` — calling `input()` with no arguments yields a `Promise<string>`. (c) `output(...)` is callable with a structured `Output`-shaped value (e.g., `output({ result: "ok" })`, `output({ goto: "ralph:check" })`, `output({ stop: true })`) and with primitive values that the parser's coerce-path accepts (e.g., `output(42)`, `output("hello")` — coerced to `{ result: "42" }` / `{ result: "hello" }` per SPEC 2.3's coercion rules). Do **not** over-pin the return type: an implementation may declare `output(...)` as `void` or `never` depending on whether it calls `process.exit()` or returns normally, so the test should assert only that `output(...)` is a callable expression that type-checks in the listed argument shapes. Avoid pinning a specific return-type symbol unless the implementation commits to `never` vs `void` — either is conformant. Together with T-TYPE-01–07 and T-MOD-04–18 (runtime behavior), this test provides the remaining compile-time type-surface coverage for the public `loopx` exports enumerated in SPEC. *(Spec 6.4, 6.5, 9.4, 9.5)*
 
 ---
 
 ## 7. Edge Cases & Boundary Tests
 
-- **T-EDGE-01**: Very long result string (~1 MB). Handled without truncation or hang. *(Spec 2.3)*
-- **T-EDGE-02**: Result containing JSON-special characters. Correct serialization/deserialization. *(Spec 2.3)*
-- **T-EDGE-03**: Script that writes stdout in multiple `write()` calls. Full output captured. *(Spec 2.3)*
+- **T-EDGE-01**: Very long result string (~1 MB). Handled without truncation or hang. Observe via `runPromise("ralph", { maxIterations: 1 })` — SPEC 7.1 specifies the CLI never prints `result` to stdout, so the programmatic API is the correct observation surface. Assert the yielded `Output.result` has the expected full length / content round-trip. *(Spec 2.3, 7.1)*
+- **T-EDGE-02**: Result containing JSON-special characters. Correct serialization/deserialization. Observe via `runPromise("ralph", { maxIterations: 1 })` (programmatic API surface per SPEC 7.1) and assert the yielded `Output.result` byte-for-byte matches the script-side input after deserialization. *(Spec 2.3, 7.1)*
+- **T-EDGE-03**: Script that writes stdout in multiple `write()` calls. Full output captured. Observe via `runPromise("ralph", { maxIterations: 1 })` (programmatic API surface per SPEC 7.1) and assert the yielded `Output.result` reflects the full concatenated stdout content. *(Spec 2.3, 7.1)*
 - **T-EDGE-04**: Script that writes to both stdout and stderr. No interleaving issues. *(Spec 6.2, 6.3)*
 - **T-EDGE-05**: Unicode in result values and env values preserved. Unicode in workflow/script names rejected (ASCII-only pattern). *(Spec 2.3, 5.3, 8.1)*
 - **T-EDGE-06**: Deeply nested goto chain (A → B → C → ... → Z) including cross-workflow hops. Correct execution order and iteration counting. *(Spec 7.1)*
@@ -1867,63 +3567,77 @@ Test the source classification logic (section 10.1) in isolation:
 
 ## 9. Pending Spec Decisions
 
-All previously identified spec problems (SP-15 through SP-31) have been resolved.
+`SPEC-PROBLEMS.md` is the source of truth for any open SPEC ambiguities tracked during TEST-SPEC development. When this file is absent or empty, no SPEC ambiguities are currently tracked.
 
-**Currently pending:**
-- SP-32 (SSH/SCP URL classification — SPEC.md section 10.1 does not mention SSH or SCP-style URLs. No tests added until resolved.)
+**Currently open ADR-0004-scoped problems.** None. The previously-open `RunOptions.env` Proxy `get` trap semantics ambiguity was resolved this cycle by amending SPEC §9.5 to specify ordinary ECMAScript `[[Get]]` semantics for value reads, equivalent to `env[key]`, exactly once per included key, with throwing `Proxy` `get` traps captured and surfaced via the standard pre-iteration error path (mirrored in §9.1's option-snapshot prose). The previously-observational tests that depended on the `get` trap firing — T-API-62f3 (throwing `get` trap surfacing), T-API-62h9 (no-retry counter on `get` trap), and the value-read assertions in T-API-52e / T-API-52e2 variant (b) — have been promoted to strict conformance pins per the new SPEC clause. T-API-62f / T-API-62h5 / T-API-62h6 remain strict pins on the `ownKeys` axis. T-API-62f2 remains observational on the `getOwnPropertyDescriptor` axis (SPEC §9.5 explicitly leaves the enumerability-determination strategy implementation-defined).
+
+**Resolved this cycle.** P-0004-01 (auto-install commit-order observability) was resolved by amending SPEC §10.10's "Trigger" bullet to make the cross-workflow auto-install order implementation-defined and not an external conformance contract; the bullet now states explicitly that "the cross-workflow order of the post-commit auto-install pass is not an external conformance contract; implementations may use their internal commit order or any other implementation-defined order," and lists the externally required guarantees (each qualifying workflow considered once, npm children non-overlapping, failure / signal rules followed). Under the new SPEC text, T-INST-110's existing scope — pinning down sequentiality / non-overlap / once-per-workflow without asserting any cross-workflow order — is the entire externally testable contract; T-INST-110's prose and the `withFakeNpm` / `LOOPX_TEST_AUTOINSTALL_PAUSE` seam wording have been updated to drop "commit order" framing in favor of "implementation-defined auto-install order." `SPEC-PROBLEMS.md` was deleted in this cycle as the file's only remaining entry was P-0004-01.
+
+P-0004-02 (signal handling during the post-commit auto-install pass when no `npm install` child is currently active) was resolved by adding a new "Signals during the auto-install pass when no npm child is active" bullet to SPEC 10.10. The clarification specifies that SIGINT / SIGTERM observed during the auto-install pass aborts the pass and exits with `128 + signal number`, that no further `.gitignore` safeguards or `npm install` children are started, that committed workflow files are not rolled back, that any `.gitignore` / `node_modules/` side effects completed before the signal observation remain on disk, and that signal termination suppresses the final auto-install aggregate failure report unless it had already been emitted. T-INST-116 / T-INST-116a–T-INST-116g remain the conformance pins for the active-child case; conformance tests for the four no-active-child windows (between sequential `npm install` invocations, during `.gitignore` safeguard work before spawning npm, after one npm child exits and before the next workflow begins processing, and after a `.gitignore` safeguard failure but before the next workflow) were added in this cycle (T-INST-116h, T-INST-116i, T-INST-116j, T-INST-116k respectively) using the new section 1.4 `LOOPX_TEST_AUTOINSTALL_PAUSE` seam in its **ordinal form** (`between-workflows-after-first`, `pre-spawn-first`, `post-exit-first`, `post-safeguard-failure-first`), which pauses loopx at the named position relative to the implementation's auto-install order long enough for the harness to deliver SIGINT / SIGTERM and then resumes if the signal does not arrive within a bounded timeout. The ordinal form is required because SPEC 10.10 explicitly leaves the cross-workflow auto-install order implementation-defined and not an external conformance contract — a name-targeted pause (e.g., `between-workflows:beta`) would assume a specific name appears at a specific position and fail conformance for an implementation that processes workflows in a different deterministic order. The seam also writes a parent-observable JSON marker on pause-entry (per the section 1.4 contract) so the test can determine which workflow names appeared in the `processed` / `current` / `remaining` partition under the implementation's auto-install order, then assert on the observed sets rather than on hard-coded `alpha` / `beta` / `gamma` ordering. Each test asserts `128 + signal number` exit, no further safeguards or npm spawns after the signal, no rollback of committed workflow files, and aggregate-report suppression (T-INST-116k additionally exercises the suppression-with-accumulated-failures sub-case via the `gitignore-replace-with-fifo:` FAULT seam applied to all three workflows so whichever workflow is processed first records the safeguard failure, composed with the `post-safeguard-failure-first` ordinal PAUSE). The complementary **already-emitted carve-out** half of SPEC 10.10's signal-termination clause (signal observed *after* the aggregate report has been written to stderr but before loopx exits → report remains observable, exit code is still `128 + signal number`) is now covered by T-INST-116l in this cycle via a `post-aggregate-report` ordinal value added to the existing `LOOPX_TEST_AUTOINSTALL_PAUSE` seam in section 1.4. The pause fires after the aggregate report has been written and the stderr write has been completed / flushed as far as the runtime stream API supports (stderr is commonly a pipe in tests, where `fsync(2)` is not portable), so the harness can deliver SIGINT during the bounded delay and verify both that the exit code is `128 + signal number` and that the already-emitted report remains observable on stderr.
+
+The previously-pending T-ENV-15f ambiguity around `KEY= value` was adopted as executable coverage under the strict reading of SPEC 8.1's "No whitespace is permitted around `=`" — see T-ENV-15f in section 4.7. The previously-pending ambiguities resolved by SPEC clarification (HTTP 3xx redirects during tarball download — SPEC 10.9; duck-typed signal with missing or non-boolean `aborted` property — SPEC 9.5; meaning of "After the commit phase ... completes" — SPEC 10.10; abort precedence × `maxIterations: 0` — SPEC 9.1 / 9.3; whitespace-only env-file lines — SPEC 8.1; install-source symlink copy semantics — SPEC 10.11; non-regular pre-existing `.gitignore` `lstat` dispatch — SPEC 10.10, formerly tracked as an earlier P-0004-01; signals during the auto-install pass when no npm child is active — SPEC 10.10, formerly tracked as P-0004-02; cross-workflow auto-install order non-normativity — SPEC 10.10, tracked as P-0004-01 in this cycle and resolved by the §10.10 "Trigger" bullet edit above) are now direct conformance pins under the corresponding tests where deterministic coverage exists (T-INST-92b, T-API-64j / T-API-64j2, T-INST-80c2, T-API-10c2 / T-API-10c3, T-ENV-08a, T-INST-55f / T-INST-55g / T-INST-55h / T-INST-55i, T-INST-112e / T-INST-112f / T-INST-112g, T-INST-116h / T-INST-116i / T-INST-116j / T-INST-116k, T-INST-110 / T-INST-110a / T-INST-110b / T-INST-114).
+
+**Tests encoding most-natural-reading interpretations of currently-silent SPEC clauses (outside ADR-0004 scope).** T-CLI-01a (`loopx version` with extra positional) and T-CLI-01b (`loopx version --help` / `-h`) encode the most-natural reading of SPEC 4.3 / 11 / 12 — that extra arguments to a no-argument subcommand are usage errors — even though SPEC 4.3 and SPEC §11 do not explicitly enumerate that case. A follow-up SPEC clarification at the SPEC 4.3 / 11 layer would let those tests be re-classified as direct conformance pins; that clarification is **outside ADR-0004 scope** and is deferred to a future non-ADR-0004 review cycle.
+
+No separate SSH/SCP pending item is present; source-classification coverage remains scoped to the source forms described in SPEC 10.1.
 
 ---
 
 ## Appendix A: Spec Requirement Traceability Matrix
 
-Maps each SPEC.md section to the test IDs that verify it.
+Maps each SPEC.md section to the test IDs that verify it. Per section 1.3, this suite targets **near-complete coverage** of SPEC.md — rows annotated with "Known gaps" are the explicitly tracked exceptions (seam-dependent failure paths that cannot be deterministically exercised black-box).
+
+**Tests covering SPEC ambiguities.** Two tests currently encode a most-natural reading of a currently-silent SPEC clause as executable coverage: T-CLI-01a / T-CLI-01b (`loopx version` extra-argument grammar — SPEC 4.3 / §11 are silent on the exact behavior, so the tests assert usage-error per the most-natural reading of SPEC 12's non-exhaustive enumeration). These tests are **outside the ADR-0004 surface** and a follow-up SPEC clarification at SPEC 4.3 / 11 (deferred to a future non-ADR-0004 review cycle) would let them be re-classified as direct conformance pins. **No ADR-0004-scoped SPEC ambiguities are currently open.** Previously-tracked ambiguity-encoding tests have been promoted to direct conformance pins after corresponding SPEC clarifications: T-ENV-08a (whitespace-only env-file lines, SPEC 8.1), T-INST-80c2 (commit-failure auto-install gating, SPEC 10.10), T-API-10c2 / T-API-10c3 (abort × `maxIterations: 0` interaction, SPEC 9.1 / 9.3), T-INST-92b (HTTP 3xx redirect, SPEC 10.9), T-API-64j / T-API-64j2 (missing or non-boolean `aborted` on duck signal, SPEC 9.5), T-INST-55f / T-INST-55g / T-INST-55h / T-INST-55i (install-source symlink copy semantics, SPEC 10.11), T-INST-112e / T-INST-112f / T-INST-112g (non-regular pre-existing `.gitignore` `lstat` dispatch — directory, `--no-install` short-circuit, and symlink-via-seam respectively, SPEC 10.10 — formerly tracked as an earlier P-0004-01), T-INST-116h / T-INST-116i / T-INST-116j / T-INST-116k (signals during the auto-install pass when no npm child is active — SPEC 10.10, formerly tracked as P-0004-02), T-INST-110 / T-INST-110a / T-INST-110b / T-INST-114 (cross-workflow auto-install order non-normativity — SPEC 10.10, tracked as P-0004-01 in this cycle and resolved by the §10.10 "Trigger" bullet edit that explicitly leaves cross-workflow order implementation-defined; T-INST-110's "Coverage scope" prose has been updated to reflect that pinning sequentiality / non-overlap / once-per-workflow is now the entire externally testable contract under the new SPEC wording), T-API-62f3 / T-API-62h9 / T-API-52e / T-API-52e2 (`RunOptions.env` Proxy `get` trap semantics during snapshot — SPEC §9.5 / §9.1, formerly tracked as the `get`-trap ambiguity now resolved in this cycle by specifying ordinary `[[Get]]` semantics). Tests classified as grammar-derived or enumeration-derived (e.g., "exactly-one-positional grammar therefore extra positionals are usage errors", "enumerated-list exclusion therefore the unenumerated case is rejected") follow logically from pinned SPEC text and are direct conformance pins.
 
 | Spec Section | Description | Test IDs |
 |-------------|-------------|----------|
-| 1 | Overview (ESM-only) | T-MOD-22 |
-| 2.1 | Workflow and Script | T-DISC-01–20c, T-DISC-14a–14b, T-DISC-21a, T-DISC-15a–15b, T-DISC-25–38, T-DISC-26a–26b, T-EXEC-15–16a, T-MOD-03a, T-MOD-03c, T-INST-50a–50b, T-INST-52b, T-INST-53a–53c, T-INST-55c–55e, T-INST-56c–56d, T-INST-62a, T-INST-64d, T-INST-74a, T-INST-75a, T-INST-76a, T-API-08t5, T-API-08t6–08t8, T-API-08z, T-API-08z2–08z4, T-API-14j5, T-API-14j6–14j8, T-API-14p, T-API-14p2–14p4, T-API-36a, T-API-47a, T-VER-24d, T-VER-24e, T-VER-25b, T-VER-25c, T-VER-26, T-VER-26a–26c, T-VER-27a–27c |
-| 2.2 | Loop (state machine, goto) | T-LOOP-01–05, T-LOOP-15a, T-LOOP-16–19, T-LOOP-19a–19b, T-LOOP-30–43, T-LOOP-30a, T-LOOP-31a–31c, T-LOOP-32a, T-EXEC-16b, T-MOD-05a, T-MOD-21a, T-CLI-111a, T-API-08ab, T-API-08t2–08t8, T-API-14j2–14j8, T-API-14r, T-API-35e, T-API-48a, T-VER-25b, T-VER-25c, T-VER-27, T-VER-27a–27c |
-| 2.3 | Structured Output | T-PARSE-01–29, T-PARSE-12a, T-PARSE-20a, F-PARSE-01–05 |
+| 1 | Overview (ESM-only) | T-MOD-22 (package-shape contract; runtime `require()` outcome is not asserted), T-MOD-22a (package `name` metadata), T-MOD-22b (`engines.node` ≥ 20.6 if declared) |
+| 2.1 | Workflow and Script | T-DISC-01–20c, T-DISC-07a, T-DISC-07b, T-DISC-07c, T-DISC-14a–14b, T-DISC-21a, T-DISC-24a, T-DISC-24b, T-DISC-15a–15b, T-DISC-25–38, T-DISC-26a–26b, T-DISC-30c, T-DISC-30d, T-DISC-30e, T-EXEC-15–16a, T-EXEC-15a, T-EXEC-15b, T-EXEC-15c, T-MOD-03a, T-MOD-03c, T-INST-42m, T-INST-42n, T-INST-50a–50b, T-INST-52b, T-INST-53a–53c, T-INST-55c–55e, T-INST-56c–56h, T-INST-62a, T-INST-63g, T-INST-64d, T-INST-74a, T-INST-75a, T-INST-76a, T-INST-110c, T-API-08t5, T-API-08t6–08t8, T-API-08z, T-API-08z2–08z4, T-API-14j5, T-API-14j6–14j8, T-API-14p, T-API-14p2–14p4, T-API-36a, T-API-47a, T-API-65j, T-VER-24d, T-VER-24e, T-VER-25b, T-VER-25c, T-VER-26, T-VER-26a–26c, T-VER-27a–27c |
+| 2.2 | Loop (state machine, goto) | T-LOOP-01–05, T-LOOP-13a, T-LOOP-15a, T-LOOP-15b, T-LOOP-16–19, T-LOOP-19a–19b, T-LOOP-30–43, T-LOOP-30a, T-LOOP-31a–31c, T-LOOP-32a, T-LOOP-44, T-LOOP-45, T-LOOP-46, T-EXEC-16b, T-MOD-05a, T-MOD-21a, T-CLI-111a, T-API-08ab, T-API-08t2–08t8, T-API-14j2–14j8, T-API-14r, T-API-24i, T-API-24j, T-API-35e, T-API-48a, T-VER-25b, T-VER-25c, T-VER-27, T-VER-27a–27c |
+| 2.3 | Structured Output | T-PARSE-01–29, T-PARSE-04a, T-PARSE-12a, T-PARSE-13a, T-PARSE-17a, T-PARSE-20a, T-LOOP-15b, T-CLI-23a, T-TMP-16b, T-MOD-13q, F-PARSE-01–05 |
 | 3.1 | Global Install | T-INST-GLOBAL-01, T-INST-GLOBAL-01a |
-| 3.2 | Local Version Pinning & Delegation | T-DEL-01–27, T-DEL-14a, T-DEL-14b, T-VER-01–27, T-VER-04a, T-VER-07a–07f, T-VER-10a–10b, T-VER-11a, T-VER-11b, T-VER-11c, T-VER-12a–12b, T-VER-13a, T-VER-13b, T-VER-13c, T-VER-14a, T-VER-15a, T-VER-18a, T-VER-19a–19c, T-VER-20a, T-VER-23a, T-VER-24a, T-VER-24b, T-VER-24c, T-VER-24d, T-VER-24e, T-VER-25a, T-VER-25b, T-VER-25c, T-VER-26a–26c, T-VER-27a–27c, T-CLI-119, T-CLI-119c, T-CLI-119e–119f, T-CLI-119h, T-CLI-119i–119k, T-MOD-03b, T-API-08aa, T-API-08ab, T-API-08b, T-API-08g, T-API-08o, T-API-08q, T-API-08s–08v, T-API-08u2, T-API-08u3, T-API-08w–08y, T-API-08z, T-API-08z2–08z4, T-API-08t2–08t8, T-API-14b2–14b4, T-API-14i–14l, T-API-14j2–14j8, T-API-14k2, T-API-14k3, T-API-14m–14o, T-API-14p, T-API-14p2–14p4, T-API-14q, T-API-14r, T-API-20p, T-API-20p2, T-API-20p3, T-API-20q, T-API-20q2, T-API-20r, T-API-20s, T-INST-60q–60s, T-INST-72a, T-INST-73a, T-INST-74a, T-INST-75a, T-INST-76a |
-| 3.3 | Module Resolution | T-MOD-01–03, T-MOD-03a–03c, T-DEL-06, T-INST-GLOBAL-01, T-INST-GLOBAL-01a |
-| 3.4 | Bash Script Binary Access | T-MOD-19–21, T-MOD-21a |
-| 4.1 | Running Scripts (run subcommand, target validation) | T-CLI-11–13, T-CLI-27–33, T-CLI-59–60, T-CLI-64–66, T-CLI-78a–78d, T-CLI-80–81, T-CLI-85, T-CLI-96, T-CLI-107–118, T-CLI-109a, T-CLI-111a, T-CLI-114a, T-CLI-118a, T-CLI-118b, T-CLI-119a–119b, T-CLI-119d, T-CLI-119g–119h, T-CLI-119i–119k, T-DISC-33–37, T-API-08c–08d, T-API-08n, T-API-08n1, T-API-08r, T-API-08t5, T-API-08t6–08t8, T-API-08v, T-API-08w–08y, T-API-08z, T-API-08z2–08z4, T-API-14f–14h, T-API-14j5, T-API-14j6–14j8, T-API-14l, T-API-14m–14o, T-API-14p, T-API-14p2–14p4, T-API-20j–20k, T-API-20j2, T-API-20p2, T-API-20p3, T-API-20r, T-API-20s, T-API-35a–35f, T-API-36a, T-API-40–48, T-API-45a, T-API-47a, T-API-48a, T-API-44a–44c, T-LOOP-30a, T-LOOP-31a, T-LOOP-31c, T-LOOP-38–42, T-VER-24b, T-VER-24c, T-VER-24d, T-VER-24e, T-VER-25b, T-VER-25c, T-VER-26, T-VER-26a–26c, T-VER-27, T-VER-27a–27c |
-| 4.2 | Options (-n, -e, run -h, install -h, top-level -h) | T-CLI-02–06, T-CLI-07b–07c, T-CLI-07e–07g, T-CLI-07j, T-CLI-14–22f, T-CLI-19a, T-CLI-20a–20b, T-CLI-28, T-CLI-34–100, T-CLI-78a–78d, T-CLI-101–102, T-CLI-101a, T-CLI-104–106, T-CLI-119–119h, T-CLI-119i–119k, T-ENV-25b–25c, T-INST-40–49, T-INST-40a–40e, T-INST-45a, T-INST-49a–49g, T-INST-41a, T-INST-42a–42l, T-INST-43a–43b, T-INST-57a, T-INST-59a–59b, T-INST-60n, T-API-08e–08q |
-| 4.3 | Subcommands | T-SUB-01–19, T-SUB-02a–02k, T-SUB-06a–06b, T-SUB-14a–14k, T-CLI-66, T-CLI-80–81, T-MOD-21a |
-| 5.1 | Discovery | T-DISC-01–16, T-DISC-10a–10g, T-DISC-14a–14b, T-DISC-38–42c, T-DISC-39a, T-DISC-40a–40i, T-DISC-48, T-DISC-48a, T-CLI-42–43, T-CLI-104–104e, T-CLI-121–122 |
-| 5.2 | Name Collision | T-DISC-21–24, T-DISC-21a, T-DISC-40e, T-CLI-22b, T-CLI-43, T-CLI-43a, T-API-08h |
-| 5.3 | Name Restrictions | T-DISC-15a–15b, T-DISC-25–32, T-DISC-26a–26b, T-DISC-40c–40d, T-DISC-40f–40i, T-DISC-47a, T-DISC-47b, T-CLI-44, T-CLI-22d–22e, T-CLI-102, T-CLI-120, T-CLI-120a, T-CLI-120b, T-LOOP-40–42, T-EDGE-05, T-API-08i–08j, T-API-20l–20o, T-INST-52b, T-INST-60d, T-INST-60m, T-INST-63a–63e |
-| 5.4 | Validation Scope | T-DISC-43–47, T-DISC-47a, T-DISC-47b, T-SUB-02h, T-SUB-06, T-SUB-13, T-SUB-19, T-CLI-28, T-CLI-114a, T-CLI-118b, T-API-20l–20o, T-API-35c, T-API-35f, T-API-44b, T-API-44c |
-| 6.1 | Working Directory | T-EXEC-01–03, T-EXEC-03a, T-EXEC-16, T-EXEC-16b, T-API-07a, T-API-47b |
-| 6.2 | Bash Scripts | T-EXEC-05–07 |
-| 6.3 | JS/TS Scripts | T-EXEC-08–14 |
-| 6.4 | output() Function | T-MOD-04–14a, T-MOD-05a, T-MOD-13a–13p |
-| 6.5 | input() Function | T-MOD-15–18 |
-| 6.6 | Input Piping | T-LOOP-11–15, T-LOOP-15a |
-| 6.7 | Initial Input | T-LOOP-14 |
-| 7.1 | Basic Loop | T-LOOP-01–10, T-LOOP-25, T-CLI-119a–119b, T-CLI-119g–119h, T-CLI-119i–119k, T-VER-24–25, T-VER-24a, T-VER-24b, T-VER-24c, T-VER-24d, T-VER-24e, T-VER-25a, T-VER-25b, T-VER-25c, T-API-08w–08y, T-API-14m–14o, T-API-20p, T-API-20p2, T-API-20p3, T-API-20q, T-API-20q2, T-API-20r, T-API-20s |
-| 7.2 | Error Handling | T-LOOP-18–24, T-LOOP-18a, T-LOOP-19a, T-LOOP-31c, T-LOOP-34–42, T-DISC-42a–42b, T-VER-25b, T-VER-25c |
-| 7.3 | Signal Handling | T-SIG-01–08 |
-| 8.1 | Global Env Storage | T-ENV-01–15f, T-ENV-05a–05e, T-ENV-25–25c, T-CLI-22c, F-ENV-01–05, T-API-08k–08m |
-| 8.2 | Local Env Override | T-ENV-16–19, T-ENV-17a, T-ENV-25a, T-CLI-22f, T-API-08p, T-API-08p2 |
-| 8.3 | Env Injection Precedence | T-ENV-20–24, T-ENV-20a, T-ENV-20b, T-ENV-21a, T-ENV-21b, T-ENV-21c, T-ENV-21d, T-ENV-24a, T-ENV-24b, T-EXEC-03a, T-EXEC-04–04c, T-DISC-39a |
-| 9.1 | run() | T-API-01–09c, T-API-08a–08e, T-API-08g–08m, T-API-08n1, T-API-08o–08v, T-API-08u2, T-API-08u3, T-API-08w–08y, T-API-08z, T-API-08z2–08z4, T-API-08aa, T-API-08ab, T-API-08t2–08t8, T-API-10–10c, T-API-20h–20i, T-API-20j–20m, T-API-20j2, T-API-20p, T-API-20r, T-API-30–37, T-API-35a–35f, T-API-36a, T-PARSE-20a, T-TYPE-04, T-TYPE-06–07 |
-| 9.2 | runPromise() | T-API-08f, T-API-08n, T-API-08p2, T-API-11–14l, T-API-14b2–14b4, T-API-14j2–14j8, T-API-14k2, T-API-14k3, T-API-14m–14o, T-API-14p, T-API-14p2–14p4, T-API-14q, T-API-14r, T-API-14a–14a3, T-API-20n, T-API-20o, T-API-20p2, T-API-20p3, T-API-20q, T-API-20q2, T-API-20s, T-API-25–25b, T-API-38–48, T-API-45a, T-API-47a–47b, T-API-48a, T-API-44a–44c, T-PARSE-20a, T-TYPE-05–07 |
-| 9.3 | API Error Behavior | T-API-15–19, T-API-20a–20s, T-API-20p2, T-API-20p3, T-API-20q2, T-API-21c–21d |
-| 9.4 | output() and input() (script-side) | *(Same as 6.4/6.5)* |
-| 9.5 | Types / RunOptions | T-API-07–08, T-API-07a, T-API-08b–08r, T-API-08n1, T-API-08v, T-API-08w–08y, T-API-10–10c, T-API-14b2–14b4, T-API-14f–14h, T-API-14l, T-API-14m–14o, T-API-20d–20e, T-API-21–21b, T-API-22–25b, T-API-23a, T-API-24a–24b, T-API-47b, T-DISC-48a, T-TYPE-01–07 |
-| 10.1 | Source Detection | T-INST-01–01a, T-INST-02–08f, T-INST-41, T-INST-42k, T-INST-42l |
-| 10.2 | Source Type Details | T-INST-52d, T-INST-54d, T-INST-56b, T-INST-57c, T-INST-81–89, T-INST-83a, T-INST-85a–85b, T-INST-86a |
-| 10.3 | Workflow Classification | T-INST-50–56, T-INST-50a–50b, T-INST-52a, T-INST-52c, T-INST-52d, T-INST-53a–53c, T-INST-54a–54d, T-INST-55a–55e, T-INST-56a–56e, T-INST-57b, T-INST-60o, T-INST-63e, T-INST-64, T-INST-64b, T-INST-80g, T-INST-83a, T-INST-85b |
-| 10.4 | Install-time Validation | T-INST-52a–52d, T-INST-61–64, T-INST-62a, T-INST-63a–63e, T-INST-64a–64d, T-INST-72a, T-INST-73a, T-INST-74a, T-INST-75a, T-INST-76a, T-INST-80h–80j, T-INST-60a, T-INST-60e, T-INST-60g, T-INST-60h, T-INST-60n |
-| 10.5 | Collision Handling | T-INST-65–71, T-INST-67a, T-INST-70a–70d, T-INST-71a, T-INST-97, T-INST-60c, T-INST-60k, T-INST-60l, T-INST-60p |
-| 10.6 | Version Checking on Install | T-INST-72–76, T-INST-72a, T-INST-73a, T-INST-74a, T-INST-75a, T-INST-76a, T-INST-97b, T-VER-12–13, T-VER-12a–12b, T-VER-13a, T-VER-13b, T-VER-13c, T-VER-15, T-VER-15a, T-VER-17, T-VER-22, T-VER-23a, T-INST-80d–80f, T-INST-54b, T-INST-54d, T-INST-60b, T-INST-60f, T-INST-60i, T-INST-60j, T-INST-60q–60s, T-DEL-25 |
-| 10.7 | Install Atomicity | T-INST-63e, T-INST-77–80j |
-| 10.8 | Selective Workflow Installation | T-INST-57–60, T-INST-57a–57c, T-INST-59a–59b, T-INST-60a–60p, T-INST-60q–60s, T-INST-64c |
-| 10.9 | Common Rules | T-INST-90–96, T-INST-97a |
-| 11.1 | Top-Level Help | T-CLI-02–06, T-CLI-07e–07g, T-CLI-07j, T-CLI-28, T-CLI-39, T-CLI-61, T-CLI-65, T-CLI-90–91 |
-| 11.2 | Run Help | T-CLI-40–43a, T-CLI-40a, T-CLI-62, T-CLI-67–78, T-CLI-84, T-CLI-92–95, T-CLI-101–102, T-CLI-101a, T-CLI-104–106, T-CLI-104a–104e, T-CLI-120–122, T-CLI-120a, T-CLI-120b, T-DISC-10d–10g, T-DISC-15b, T-DISC-38, T-DISC-40b–40e, T-DISC-40g–40i, T-VER-19, T-VER-19a–19c |
-| 11.3 | Install Help | T-INST-41–42, T-INST-41a, T-INST-42a–42l, T-INST-49a–49g |
-| 12 | Exit Codes | T-EXIT-01–17 |
-| 13 | Summary of Special Values | *(Summary-only section — LOOPX_BIN: T-MOD-19–21, T-MOD-21a, T-ENV-20, T-ENV-20a, T-ENV-20b, T-DEL-05; LOOPX_PROJECT_ROOT: T-EXEC-03–03a, T-ENV-21, T-ENV-21a, T-ENV-21d; LOOPX_WORKFLOW: T-EXEC-04–04c, T-ENV-21b, T-ENV-21c; LOOPX_DELEGATED: T-DEL-04, T-DEL-07, T-DEL-09, T-ENV-24a; `index` convention: T-DISC-17–20, T-CLI-108–110, T-CLI-109a, T-INST-64, T-INST-64b–64d, T-INST-74a, T-INST-75a, T-INST-76a, T-LOOP-31c, T-API-20j2, T-API-20p2, T-API-20p3, T-API-45a, T-VER-24d, T-VER-24e, T-VER-25b, T-VER-25c; `:` delimiter: T-CLI-112–118, T-CLI-120a, T-CLI-120b, T-LOOP-36–42, T-API-30–44, T-INST-63b, T-INST-63c, T-INST-63e)* |
+| 3.2 | Local Version Pinning & Delegation | T-DEL-01–30 (incl. T-DEL-04a, T-DEL-07a, T-DEL-09a, T-DEL-15a, T-DEL-15b, T-DEL-26a, T-DEL-28, T-DEL-28a, T-DEL-28b, T-DEL-28c, T-DEL-28d, T-DEL-28e, T-DEL-29, T-DEL-30), T-DEL-14a, T-DEL-14b, T-VER-01–27, T-VER-04a, T-VER-07a–07f, T-VER-09a, T-VER-10a–10b, T-VER-11a, T-VER-11b, T-VER-11b2, T-VER-11c, T-VER-11d, T-VER-12a–12c, T-VER-13a, T-VER-13b, T-VER-13b2, T-VER-13c, T-VER-13d, T-VER-14a, T-VER-14b, T-VER-14c, T-VER-14d, T-VER-15a, T-VER-15b, T-VER-15c, T-VER-15d, T-VER-18a, T-VER-19a–19c, T-VER-20a, T-VER-23a, T-VER-24a, T-VER-24b, T-VER-24c, T-VER-24d, T-VER-24e, T-VER-25a, T-VER-25b, T-VER-25c, T-VER-26a–26c, T-VER-27a–27c, T-CLI-119, T-CLI-119c, T-CLI-119e–119f, T-CLI-119h, T-CLI-119i–119k, T-CLI-RUN-ORDER-05, T-MOD-03b, T-MOD-03e, T-MOD-03e-bun, T-API-07c, T-API-08aa, T-API-08ab, T-API-08b, T-API-08g, T-API-08o, T-API-08q, T-API-08s–08v, T-API-08u2, T-API-08u3, T-API-08w–08y, T-API-08z, T-API-08z2–08z4, T-API-08t2–08t8, T-API-14b2–14b4, T-API-14i–14l, T-API-14j2–14j8, T-API-14k2, T-API-14k3, T-API-14m–14o, T-API-14p, T-API-14p2–14p4, T-API-14q, T-API-14r, T-API-20p, T-API-20p2, T-API-20p3, T-API-20q, T-API-20q2, T-API-20r, T-API-20s, T-API-68r (`.return()` carve-out suppresses workflow `package.json` warnings parameterized over four SPEC 3.2 failure-mode branches), T-API-69q (`.throw()` counterpart), T-ENV-24a6 (LOOPX_DELEGATED four-tier precedence — startup-reserved-only on the loopx side, ordinary non-protocol variable on the spawned-script side), T-INST-60q–60s, T-INST-72a, T-INST-73a, T-INST-74a, T-INST-75a, T-INST-76a, T-INST-111c, T-INST-113c, T-INST-113c2, T-INST-113d, T-INST-113d2, T-INST-113e, T-INST-113f, T-INST-113g, T-TMP-12f, T-TMP-12f2, T-TMP-12f3, T-TMP-12f4, T-TMP-12g (`run()` programmatic version-check-before-tmpdir-creation parameterized over four SPEC 3.2 branches), T-TMP-12h (`runPromise()` counterpart), T-PWD-06 |
+| 3.3 | Module Resolution | T-MOD-01–03, T-MOD-03a–03e, T-MOD-03e-bun, T-MOD-03f, T-MOD-03f-bun, T-MOD-03g, T-MOD-03g-bun, T-MOD-03h, T-MOD-03h-bun, T-DEL-06, T-INST-GLOBAL-01, T-INST-GLOBAL-01a |
+| 3.4 | Bash Script Binary Access | T-MOD-19–21, T-MOD-20a, T-MOD-21a |
+| 4.1 | Running Scripts (run subcommand, target validation) | T-CLI-11–13, T-CLI-27–33, T-CLI-59–60, T-CLI-64–66, T-CLI-78a–78d, T-CLI-80–81, T-CLI-85, T-CLI-96, T-CLI-107–118, T-CLI-109a, T-CLI-111a, T-CLI-114a, T-CLI-118a, T-CLI-118b, T-CLI-119a–119b, T-CLI-119d, T-CLI-119g–119h, T-CLI-119i–119k, T-CLI-RUN-DASHDASH-01, T-CLI-RUN-DASHDASH-02, T-CLI-RUN-DASHDASH-03, T-CLI-RUN-DASHDASH-04, T-CLI-RUN-DASHDASH-05, T-CLI-RUN-DASHDASH-06, T-CLI-RUN-DASHDASH-07, T-CLI-RUN-DASHDASH-08, T-CLI-RUN-DASHDASH-09, T-CLI-RUN-DASHDASH-10, T-CLI-RUN-DASHDASH-11, T-CLI-RUN-DASHDASH-12, T-CLI-RUN-DASHDASH-13, T-CLI-RUN-NAMEVAL-01, T-CLI-RUN-NAMEVAL-02, T-CLI-RUN-NAMEVAL-03, T-CLI-RUN-NAMEVAL-04, T-CLI-RUN-NAMEVAL-05, T-CLI-RUN-NAMEVAL-06 (`name=value` precedes target — positional-order symmetric variant of NAMEVAL-03), T-CLI-RUN-NAMEVAL-07 (option-flag-then-`name=value`-then-target ordering), T-CLI-RUN-INHERIT-01 (positive shell-env-prefix → inherited-env tier reaches the spawned script), T-CLI-RUN-ORDER-01, T-CLI-RUN-ORDER-02, T-CLI-RUN-ORDER-03, T-CLI-RUN-ORDER-04, T-CLI-RUN-ORDER-05, T-DISC-30e, T-DISC-33–37, T-API-08c–08d, T-API-08n, T-API-08n1, T-API-08r, T-API-08t5, T-API-08t6–08t8, T-API-08v, T-API-08w–08y, T-API-08z, T-API-08z2–08z4, T-API-14f–14h, T-API-14j5, T-API-14j6–14j8, T-API-14l, T-API-14m–14o, T-API-14p, T-API-14p2–14p4, T-API-20j–20k, T-API-20j2, T-API-20p2, T-API-20p3, T-API-20r, T-API-20s, T-API-35a–35f, T-API-36a, T-API-40–48, T-API-45a, T-API-47a, T-API-48a, T-API-44a–44c, T-API-65i, T-API-65j, T-LOOP-30a, T-LOOP-31a, T-LOOP-31c, T-LOOP-38–42, T-SIG-27, T-SIG-28, T-TMP-12-cli-no-target (CLI bare `loopx run` parser-error → no tmpdir created), T-TMP-16b, T-TMP-16g (CLI bare-name `goto` missing-script cleanup), T-TMP-16h (`runPromise()` counterpart), T-TMP-16i (`run()` counterpart), T-TMP-16j (name-restriction-violation `goto` cleanup across all three surfaces), T-VER-24b, T-VER-24c, T-VER-24d, T-VER-24e, T-VER-25b, T-VER-25c, T-VER-26, T-VER-26a–26c, T-VER-27, T-VER-27a–27c |
+| 4.2 | Options (-n, -e, run -h, install -h, top-level -h, --no-install) | T-CLI-02–06, T-CLI-07b–07c, T-CLI-07e–07g, T-CLI-07j, T-CLI-14–22f, T-CLI-19a, T-CLI-20a–20b, T-CLI-28, T-CLI-34–100, T-CLI-69a, T-CLI-70a, T-CLI-71a–71b, T-CLI-78a–78d, T-CLI-101–102, T-CLI-101a, T-CLI-104–106, T-CLI-119–119h, T-CLI-119i–119k, T-CLI-123, T-CLI-123a, T-CLI-124, T-CLI-124a, T-CLI-125, T-CLI-126, T-CLI-RUN-DASHDASH-01, T-CLI-RUN-DASHDASH-02, T-CLI-RUN-DASHDASH-03, T-CLI-RUN-DASHDASH-04, T-CLI-RUN-DASHDASH-05, T-CLI-RUN-DASHDASH-06, T-CLI-RUN-DASHDASH-07, T-CLI-RUN-DASHDASH-08, T-CLI-RUN-DASHDASH-09, T-CLI-RUN-DASHDASH-10, T-CLI-RUN-DASHDASH-11, T-CLI-RUN-DASHDASH-12, T-CLI-RUN-DASHDASH-13, T-CLI-RUN-NAMEVAL-04, T-CLI-RUN-NAMEVAL-05, T-CLI-RUN-INHERIT-01 (per-run CLI parameterization via shell env prefix — the sole positive CLI surface), T-CLI-RUN-ORDER-01, T-CLI-RUN-ORDER-02, T-CLI-RUN-ORDER-03, T-CLI-RUN-ORDER-04, T-CLI-RUN-ORDER-05, T-CLI-TOP-DASHDASH-01, T-ENV-25b–25c, T-ENV-26b, T-ENV-27b, T-API-59f (CLI `-e` does not redirect global env-file lookup via `XDG_CONFIG_HOME` — closes the CLI surface for the SPEC 8.1 inherited-env rule), T-API-59g (CLI `-e` `HOME`-fallback counterpart), T-INST-40–49, T-INST-40a–40f, T-INST-44a, T-INST-44b, T-INST-44c, T-INST-44d, T-INST-44e, T-INST-44f (no short alias for `--no-install` — parser rejects `-n` / `-N` / `-i` / `-I` candidates per SPEC 4.2 "No short form"), T-INST-45a, T-INST-49a–49g, T-INST-41a, T-INST-42a–42l, T-INST-43a–43b, T-INST-57a, T-INST-59a–59b, T-INST-60n, T-INST-111c, T-INST-DASHDASH-01, T-INST-DASHDASH-02, T-INST-DASHDASH-03, T-INST-DASHDASH-04, T-API-08e–08q, T-API-20d2, T-API-20e2, T-TMP-12-cli-unknown-flag, T-TMP-12-cli-duplicate-n, T-TMP-12-cli-duplicate-e, T-TMP-12-cli-help-with-unknown, T-TMP-12-cli-help-with-dashdash (CLI usage-error / help-short-circuit invocations create no `LOOPX_TMPDIR` per SPEC 7.4 "reaches execution" boundary) |
+| 4.3 | Subcommands | T-SUB-01–19, T-SUB-02a–02k, T-SUB-05a, T-SUB-06a–06b, T-SUB-06c, T-SUB-06d, T-SUB-06e, T-SUB-06f, T-SUB-11e, T-SUB-14a–14k, T-SUB-14l, T-SUB-19a, T-SUB-20–23, T-SUB-24, T-SUB-25, T-SUB-26, T-SUB-27, T-SUB-28, T-SUB-29, T-SUB-29a, T-SUB-29b, T-SUB-29c, T-SUB-29d, T-CLI-01, T-CLI-01a, T-CLI-01b, T-CLI-66, T-CLI-80–81, T-DEL-26a, T-MOD-21a |
+| 5.1 | Discovery | T-DISC-01–16, T-DISC-09a, T-DISC-09b, T-DISC-10a–10g, T-DISC-14a–14b, T-DISC-15c, T-DISC-38–42g, T-DISC-39a, T-DISC-40a–40i, T-DISC-40j, T-DISC-40k, T-DISC-48, T-DISC-48a, T-CLI-42–43, T-CLI-104–104e, T-CLI-121–122, T-CLI-RUN-ORDER-03, T-CLI-RUN-ORDER-04, T-ENV-26d, T-ENV-26e, T-SIG-24, T-SIG-25, T-API-65s, T-API-65t, T-TMP-12-programmatic-discovery-missing-loopx, T-INST-56h, T-INST-56i, T-INST-64e, T-INST-55o, T-INST-55p, T-INST-55q, T-INST-55r, T-INST-55s, T-INST-55t |
+| 5.2 | Name Collision | T-DISC-21–24, T-DISC-21a, T-DISC-24a, T-DISC-24b, T-DISC-40e, T-CLI-22b, T-CLI-43, T-CLI-43a, T-API-08h, T-INST-42n, T-INST-55r |
+| 5.3 | Name Restrictions | T-DISC-15a–15b, T-DISC-25–32, T-DISC-26a–26b, T-DISC-30c, T-DISC-30d, T-DISC-30e, T-DISC-40c–40d, T-DISC-40f–40i, T-DISC-47a, T-DISC-47b, T-CLI-44, T-CLI-22d–22e, T-CLI-102, T-CLI-120, T-CLI-120a, T-CLI-120b, T-LOOP-40–42, T-EDGE-05, T-API-08i–08j, T-API-20l–20o, T-API-65t, T-INST-52b, T-INST-55o, T-INST-55q, T-INST-60d, T-INST-60m, T-INST-63a–63e, T-INST-63f, T-INST-63g, T-SIG-25 |
+| 5.4 | Validation Scope | T-DISC-43–47, T-DISC-47a, T-DISC-47b, T-SUB-02h, T-SUB-06, T-SUB-13, T-SUB-19, T-SUB-20, T-SUB-21, T-SUB-22, T-SUB-23, T-CLI-28, T-CLI-114a, T-CLI-118b, T-API-20l–20o, T-API-65s, T-API-65t, T-SIG-25, T-TMP-12-programmatic-discovery-validation. **Note:** T-API-35c / 35f / 44b / 44c do **not** appear here — SPEC 4.1 leaves programmatic-API pre-iteration error ordering implementation-defined (outside of the pinned section 9.3 rules), so those tests no longer assert sibling-validation-wins ordering on the API surface. CLI T-CLI-114a / T-CLI-118b remain as the validation-scope-ordering surface. |
+| 6.1 | Working Directory (project-root-unified cwd) | T-EXEC-01–03, T-EXEC-03a, T-EXEC-03b, T-EXEC-03c (Bash loop-reset cwd isolation — no-`goto` reset path counterpart to T-EXEC-03b's goto path), T-EXEC-16, T-EXEC-16b, T-EXEC-16c, T-EXEC-16d (JS/TS loop-reset cwd isolation — no-`goto` reset path counterpart to T-EXEC-16c's goto path), T-API-07, T-API-07a, T-API-07b, T-API-07c, T-API-47b, T-WFDIR-01–14, T-WFDIR-13a, T-PWD-01–06, T-PWD-07, T-PWD-08, T-SYM-01–05, T-SYM-02c, T-SYM-04a, T-SYM-04b, T-SYM-04c, T-SYM-02d (CLI effective-cwd directory identity under symlinked CLI cwd — pins SPEC 6.1's "directory identity vs. string spelling" clause on the CLI surface, the CLI counterpart to T-SYM-04d's programmatic-surface coverage), T-SYM-04d (effective-cwd directory identity vs. string spelling under symlinked `RunOptions.cwd` — pins SPEC 6.1's "directory identity vs. string spelling" clause on the programmatic surface, complementing T-SYM-03 / T-SYM-04's string-spelling-only assertions), T-SYM-06, T-SYM-06a, T-SYM-07, T-SYM-07a, T-SYM-07b |
+| 6.2 | Bash Scripts | T-EXEC-05–07, T-EXEC-07a, T-EXEC-07b, T-EXEC-03c (Bash loop-reset cwd isolation), T-LOOP-24a, T-WFDIR-09a, T-WFDIR-09b, T-WFDIR-09c, T-WFDIR-09d, T-WFDIR-01, T-SYM-02c, T-SYM-04c, T-SYM-06a |
+| 6.3 | JS/TS Scripts | T-EXEC-08–14, T-EXEC-13c, T-EXEC-13d, T-EXEC-13e, T-EXEC-13f, T-EXEC-13g, T-EXEC-13h, T-EXEC-13i, T-EXEC-13j, T-EXEC-13k, T-EXEC-13l, T-EXEC-13m, T-EXEC-16d (JS/TS loop-reset cwd isolation), T-LOOP-24a, T-SYM-07, T-SYM-07a, T-SYM-07b |
+| 6.4 | output() Function | T-MOD-04–14a, T-MOD-05a, T-MOD-13a, T-MOD-13a2, T-MOD-13b–13p, T-MOD-13q, T-DEL-26a, T-TYPE-08 |
+| 6.5 | input() Function | T-MOD-15–18, T-TYPE-08, T-INST-GLOBAL-01, T-INST-GLOBAL-01a |
+| 6.6 | Input Piping | T-LOOP-11–15, T-LOOP-13a, T-LOOP-15a, T-LOOP-15b |
+| 6.7 | Initial Input | T-LOOP-14, T-LOOP-13a, T-INST-GLOBAL-01, T-INST-GLOBAL-01a |
+| 7.1 | Basic Loop | T-LOOP-01–10, T-LOOP-24a, T-LOOP-25, T-LOOP-44, T-LOOP-45, T-LOOP-46, T-CLI-23a, T-CLI-119a–119b, T-CLI-119g–119h, T-CLI-119i–119k, T-CLI-RUN-ORDER-05, T-DISC-14b, T-VER-24–25, T-VER-24a, T-VER-24b, T-VER-24c, T-VER-24d, T-VER-24e, T-VER-25a, T-VER-25b, T-VER-25c, T-API-08w–08y, T-API-10b2, T-API-10c2, T-API-10c3, T-API-14m–14o, T-API-20p, T-API-20p2, T-API-20p3, T-API-20q, T-API-20q2, T-API-20r, T-API-20s, T-API-24i, T-API-24j, T-API-65h, T-API-65i, T-API-65j, T-API-68p (`.return()` carve-out suppresses local env-file parser warnings — SPEC 7.1 step 2 step never runs), T-API-68q (global env-file warning suppression — same step), T-API-68r (workflow `package.json` warning suppression across four SPEC 3.2 branches — SPEC 7.1 step 5 never runs), T-API-69o (`.throw()` local env-file warning suppression), T-API-69p (`.throw()` global env-file warning suppression), T-API-69q (`.throw()` workflow `package.json` warning suppression), T-SIG-27, T-SIG-28, T-TMP-12f, T-TMP-12f2, T-TMP-12f3, T-TMP-12f4, T-TMP-12g (`run()` programmatic step 5 → step 6 ordering parameterized over four SPEC 3.2 branches), T-TMP-12h (`runPromise()` counterpart), T-EDGE-01, T-EDGE-02, T-EDGE-03, T-MOD-03c, T-MOD-03d, T-MOD-03e, T-MOD-03e-bun, T-MOD-03f, T-MOD-03f-bun |
+| 7.2 | Error Handling | T-LOOP-18–24, T-LOOP-18a, T-LOOP-19a, T-LOOP-24a, T-LOOP-31c, T-LOOP-34–42, T-DISC-42a–42g, T-TMP-12a, T-TMP-12b, T-TMP-12c, T-TMP-15a, T-TMP-15b, T-TMP-16b, T-TMP-16c, T-TMP-16d, T-TMP-16e, T-TMP-16f, T-TMP-16g, T-TMP-16h, T-TMP-16i, T-TMP-16j, T-TMP-35d, T-TMP-35e, T-TMP-37c (rule-3 hard-link `nlink`-safety / cleanup-warning cardinality), T-TMP-42a (cleanup-failure warning branch × non-zero script exit terminal), T-TMP-42b (cleanup-failure warning branch × abort terminal), T-TMP-38 (cleanup idempotence under racing SIGINT → SIGTERM via the section 1.4 `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE=cleanup-start` seam), T-TMP-38a (programmatic `run()` cleanup idempotence — abort observed first, racing `.return()` during cleanup-start), T-TMP-38a2 (symmetric counterpart — **mid-loop `.return()` observed first**, racing abort during cleanup-start — closes the inverted-observation-order half of the `.return()` axis on the warning-cardinality surface), T-TMP-38b (programmatic `runPromise()` cleanup idempotence — non-zero script exit observed first, racing abort during cleanup-start), T-TMP-38c (programmatic `run()` cleanup idempotence — abort observed first, racing `.throw()` during cleanup-start — closes the `.throw()` axis of SPEC 7.2's "abort concurrent with consumer `.return()` / `.throw()`" enumeration), T-TMP-38d (programmatic `run()` cleanup idempotence — **abort after final yield** observed first, racing `.throw()` during cleanup-start — closes the warning-cardinality axis of SPEC 7.2's "abort after final yield concurrent with consumer `.throw()`" enumeration on the rule-3 warning-emitting branch), T-TMP-38d2 (symmetric counterpart — **post-final-yield `.throw()`** observed first, racing abort during cleanup-start — closes the inverted-observation-order half of the same warning-cardinality axis), T-TMP-38e (programmatic `runPromise()` cleanup idempotence — **child spawn failure concurrent with abort** across both observation orders — closes the warning-cardinality axis of SPEC 7.2's "child spawn failure concurrent with abort" enumeration via `LOOPX_TEST_CLEANUP_FAULT=recursive-remove-fail` combined with the `child-spawn-failure` and `child-spawn-attempt` pause seams), T-TMP-38f (CLI cleanup idempotence under racing **SIGTERM → SIGINT** — inverted-order parity for T-TMP-38, pinning SPEC 7.2 / 7.4's SIGINT/SIGTERM symmetry on the racing-signal idempotence and exit-code-precedence axes), T-TMP-39 (warning cardinality across racing terminals on the rule-5 mismatched-directory branch), T-TERM-01 (racing non-zero exit vs. abort across both observation orders via the `child-exit-handler` and `abort-listener` pause seams), T-TERM-02 (racing abort vs. consumer `.return()` across both observation orders via the `abort-listener` and `consumer-return-observed` pause seams), T-TERM-02c (racing abort vs. consumer `.throw()` — abort observed first, post-pause `.throw()` does not displace the abort outcome), T-TERM-02d (racing consumer `.throw()` vs. abort — `.throw()` observed first, surfaced outcome is **not** abort — uses the `consumer-throw-observed` pause seam declared in section 1.4), T-TERM-03 (racing signal during cleanup of a prior signal — surfaced exit code reflects first-observed signal), T-TERM-04 (racing child spawn failure vs. abort across both observation orders via the `child-spawn-failure` and `child-spawn-attempt` pause seams, with NUL-in-`RunOptions.env` as the deterministic spawn-failure fixture per SPEC 7.2 / 9.5), T-ENV-26, T-ENV-26a, T-ENV-26b, T-ENV-26c, T-ENV-26d (CLI cleanup on discovered-script removed mid-loop), T-ENV-26e (CLI cleanup on discovered-script renamed mid-loop), T-ENV-26f (`run()` generator + local env-file NUL value), T-ENV-26g (`run()` generator + local env-file NUL value, zero-iteration), T-ENV-27, T-ENV-27a, T-ENV-27b, T-ENV-27c, T-ENV-27d (`run()` generator + global env-file NUL value), T-ENV-27e (`run()` generator + global env-file NUL value, zero-iteration), T-API-57, T-API-57a, T-API-57h, T-API-57i, T-CLI-19b, T-VER-25b, T-VER-25c. The explicit-precedence-rule races (pre-first-`next()` carve-out, abort-wins-over-pre-iteration, CLI pre-iteration signal-wins, abort-after-final-yield) are also covered by T-API-09d / T-API-09e, T-API-65–65o, T-SIG-20–28, etc. **Known gap (not directly covered):** T-SIG-30b / T-API-10j — signal/abort concurrent with partial tmpdir creation failure (SPEC 7.4's "If a SIGINT/SIGTERM or `AbortSignal` abort arrives concurrently with a creation failure, the signal/abort wins ..." clause) remains untested without a `LOOPX_TEST_TMPDIR_CREATION_PAUSE` pause sentinel; see section 4.11 "Narrow Pre-iteration Windows (Known Gaps)". |
+| 7.3 | Signal Handling | T-SIG-01–08, T-SIG-04a, T-SIG-05a, T-SIG-06a, T-SIG-07a, T-SIG-20, T-SIG-20a, T-SIG-21, T-SIG-22, T-SIG-23, T-SIG-24, T-SIG-25, T-SIG-27, T-SIG-28, T-SIG-30, T-TMP-18a, T-TMP-18b, T-INST-116, T-INST-116a, T-INST-116b, T-INST-116b2 (SIGTERM-axis remaining-workflows-not-processed parity for T-INST-116b), T-INST-116c, T-INST-116d, T-INST-116d2 (SIGTERM-axis partial-`node_modules/`-not-cleaned parity for T-INST-116d), T-INST-116e, T-INST-116f, T-INST-116g, T-INST-116h, T-INST-116h2 (SIGTERM-axis `between-workflows-after-first` parity for T-INST-116h), T-INST-116i, T-INST-116i2 (SIGTERM-axis `pre-spawn-first` parity for T-INST-116i), T-INST-116j, T-INST-116j2, T-INST-116j3 (SIGTERM-axis `post-exit-first` × non-zero-npm-exit parity for T-INST-116j2), T-INST-116k, T-INST-116k2 (SIGTERM-axis `post-safeguard-failure-first` parity for T-INST-116k), T-INST-116l, T-INST-116l2 (SIGTERM-axis `post-aggregate-report` carve-out parity for T-INST-116l), T-INST-116m (SIGINT × `post-spawn-failure-first` × spawn-failure accumulator state — closes the no-active-child × signal-termination-suppression contract on the `npm-install-spawn-failure` accumulator state, alongside T-INST-116j2 (non-zero-exit accumulator) and T-INST-116k (safeguard-failure accumulator)), T-INST-116m2 (SIGTERM-axis parity for T-INST-116m), T-API-10d, T-API-10d-promise, T-API-10e, T-API-10e-promise, T-API-10f, T-API-10f-throw, T-API-10g, T-API-10h. **Known gaps (not directly covered):** T-SIG-26 — the pre-handler-installation window described in the final paragraph of Spec 7.3 remains untested without a startup-delay seam; T-SIG-29 — signal after `LOOPX_TMPDIR` creation but before first child spawn remains untested without a post-tmpdir-pre-spawn sentinel seam; T-SIG-30b — CLI signal concurrent with partial tmpdir creation failure remains untested without a `LOOPX_TEST_TMPDIR_CREATION_PAUSE` pause sentinel (see section 4.11 "Narrow Pre-iteration Windows (Known Gaps)"). |
+| 7.4 | Run-scoped Temporary Directory (LOOPX_TMPDIR) | T-TMP-01–11, T-TMP-02a, T-TMP-08a (concurrent same-project on `runPromise()` surface), T-TMP-08b (concurrent same-project on CLI `loopx run` surface — pins ADR-0004's "parallel `loopx run` invocations do not clobber each other" guarantee on the CLI surface, complementing T-TMP-08a's programmatic-surface coverage and T-TMP-08's independent-projects coverage), T-TMP-08c (concurrent same-project on `run()` generator surface — closes the four-cell concurrent-isolation matrix `{independent / same project} × {generator / promise / CLI}`), T-TMP-11a (`run()` generator zero-iteration tmpdir non-creation — generator-surface counterpart to T-TMP-11's `runPromise()` coverage and T-TMP-10's CLI coverage), T-TMP-12 (incl. T-TMP-12-global-env-unreadable, T-TMP-12-invalid-maxIterations, T-TMP-12-invalid-options-shape, T-TMP-12-invalid-env-shape, T-TMP-12-invalid-env-value, T-TMP-12-invalid-target, T-TMP-12-invalid-cwd, T-TMP-12-invalid-envFile, T-TMP-12-programmatic-discovery-missing-loopx, T-TMP-12-programmatic-discovery-validation), T-TMP-12-cli (incl. T-TMP-12-cli-global-env-unreadable), T-TMP-12-cli-usage (incl. T-TMP-12-cli-no-target, T-TMP-12-cli-unknown-flag, T-TMP-12-cli-duplicate-n, T-TMP-12-cli-duplicate-e, T-TMP-12-cli-help-with-unknown, T-TMP-12-cli-help-with-dashdash — parser-error / help-short-circuit invocations do not "reach execution" per SPEC 7.4 and create no tmpdir), T-TMP-13, T-TMP-13a, T-TMP-13b, T-TMP-14, T-TMP-14a, T-TMP-15–23, T-TMP-15a, T-TMP-15b, T-TMP-24, T-TMP-25–29, T-TMP-27a (asynchronous tmpdir creation under `runPromise()` — pins SPEC 9.2 / 7.4 timing), T-TMP-12a, T-TMP-12b, T-TMP-12c, T-TMP-12f, T-TMP-12f2, T-TMP-12f3, T-TMP-12f4, T-TMP-12g (`run()` step 5 → step 6 ordering, parameterized over four SPEC 3.2 warning branches), T-TMP-12h (`runPromise()` counterpart), T-TMP-16a, T-TMP-16b, T-TMP-16c, T-TMP-16d, T-TMP-16e, T-TMP-16f, T-TMP-16g (CLI bare-name `goto` missing-script cleanup — bare-name lookup-path counterpart to T-TMP-16a's qualified-target form), T-TMP-16h (`runPromise()` counterpart), T-TMP-16i (`run()` counterpart), T-TMP-16j (name-restriction-violation `goto` cleanup — closes the SPEC 4.1 name-pattern syntactic-invalidity branch complementary to T-TMP-16b's delimiter-syntax branch), T-TMP-18a, T-TMP-18b, T-TMP-22a, T-TMP-22b, T-TMP-22c, T-TMP-22d, T-TMP-22e, T-TMP-22f, T-TMP-24a, T-TMP-24b, T-TMP-24c, T-TMP-24d, T-TMP-25a, T-TMP-25b, T-TMP-26-temp, T-TMP-26-tmp, T-TMP-27-temp, T-TMP-27-tmp, T-TMP-28a, T-TMP-28b, T-TMP-29a, T-TMP-29b, T-TMP-29c, T-TMP-29d, T-TMP-29e, T-TMP-29f, T-TMP-29g, T-TMP-29h, T-TMP-29i, T-TMP-29j, T-TMP-29k, T-TMP-30, T-TMP-31, T-TMP-32, T-TMP-33, T-TMP-34, T-TMP-35, T-TMP-35a, T-TMP-35b, T-TMP-35c, T-TMP-35d, T-TMP-35e, T-TMP-36, T-TMP-36a, T-TMP-36b, T-TMP-37, T-TMP-37a, T-TMP-37b, T-TMP-37c (rule-3 hard-link `nlink`-safety), T-SIG-07a (between-iteration tmpdir cleanup), T-SIG-23, T-API-10b2, T-API-10c2, T-API-10c3, T-API-10e, T-API-10e-promise, T-API-10g, T-API-51a (`LOOPX_TMPDIR` stat-during-run rigor), T-API-57d, T-API-57e, T-API-57f, T-API-57f2, T-API-60, T-API-60a, T-API-60b, T-API-60c, T-API-65p, T-API-65q, T-API-65r, T-API-65s, T-API-65t, T-API-65v, T-API-65w, T-API-68g, T-API-68i, T-API-68k, T-API-68l, T-API-68m, T-API-68n, T-API-68o, T-API-68p (no-tmpdir under `.return()` carve-out for local env-file warning), T-API-68q (no-tmpdir under `.return()` for global env-file warning), T-API-68r (no-tmpdir under `.return()` across four SPEC 3.2 `package.json` warning branches), T-API-69d, T-API-69f, T-API-69g, T-API-69h, T-API-69j, T-API-69k, T-API-69l, T-API-69m, T-API-69n, T-API-69o (no-tmpdir under `.throw()` carve-out for local env-file warning), T-API-69p (no-tmpdir under `.throw()` for global env-file warning), T-API-69q (no-tmpdir under `.throw()` for workflow `package.json` warnings), T-TMP-12d (identity-capture sub-step failure via the section 1.4 `LOOPX_TEST_TMPDIR_FAULT=identity-capture-fail` seam — parameterized over CLI / `run()` / `runPromise()`), T-TMP-12d2 (identity-capture failure followed by `rmdir` failure via `LOOPX_TEST_TMPDIR_FAULT=identity-capture-fail-rmdir-fail` — SPEC 7.4 cleanup-failure-during-creation-failure-handling for the `rmdir` branch, asserting original creation error is surfaced and warning cardinality is one), T-TMP-12e (mode-securing sub-step failure via `LOOPX_TEST_TMPDIR_FAULT=mode-secure-fail`), T-TMP-12e2 (mode-secure failure followed by recursive-remove failure via `LOOPX_TEST_TMPDIR_FAULT=mode-secure-fail` × `LOOPX_TEST_CLEANUP_FAULT=recursive-remove-fail` — SPEC 7.4 cleanup-failure-during-creation-failure-handling for the rule-4 recursive-remove branch of the cleanup-safety routine, asserting original creation error is surfaced and warning cardinality is one), T-TMP-12e3 (mode-secure failure followed by top-level `lstat` failure via `LOOPX_TEST_TMPDIR_FAULT=mode-secure-fail` × `LOOPX_TEST_CLEANUP_FAULT=lstat-fail` — SPEC 7.4 cleanup-failure-during-creation-failure-handling for the top-level-`lstat`-failure branch of the cleanup-safety routine), T-TMP-38 (cleanup idempotence under racing terminal triggers via `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE=cleanup-start`), T-TMP-38a (programmatic `run()` cleanup idempotence — abort observed first, racing `.return()` during cleanup-start), T-TMP-38a2 (symmetric counterpart — mid-loop `.return()` observed first, racing abort during cleanup-start — warning-cardinality axis on the rule-3 warning-emitting branch), T-TMP-38b (programmatic `runPromise()` cleanup idempotence — non-zero script exit observed first, racing abort during cleanup-start), T-TMP-38c (programmatic `run()` cleanup idempotence — abort observed first, racing `.throw()` during cleanup-start), T-TMP-38d (programmatic `run()` cleanup idempotence — **abort after final yield** observed first, racing `.throw()` during cleanup-start — warning-cardinality axis of SPEC 7.2's "abort after final yield concurrent with consumer `.throw()`" enumeration on the rule-3 warning-emitting branch), T-TMP-38d2 (symmetric counterpart — **post-final-yield `.throw()`** observed first, racing abort during cleanup-start — closes the inverted-observation-order half of the same warning-cardinality axis), T-TMP-38e (programmatic `runPromise()` cleanup idempotence — **child spawn failure concurrent with abort** across both observation orders — warning-cardinality axis of SPEC 7.2's "child spawn failure concurrent with abort" enumeration via `LOOPX_TEST_CLEANUP_FAULT=recursive-remove-fail` × `child-spawn-failure` / `child-spawn-attempt` pause seams), T-TMP-39 (warning cardinality on the rule-5 mismatched-directory branch under racing terminals), T-TMP-40 (top-level `lstat` failure non-ENOENT via `LOOPX_TEST_CLEANUP_FAULT=lstat-fail`), T-TMP-41 (symlink `unlink` failure via `LOOPX_TEST_CLEANUP_FAULT=symlink-unlink-fail`), T-TMP-42 (recursive removal failure on identity-matched directory via `LOOPX_TEST_CLEANUP_FAULT=recursive-remove-fail`), T-TMP-42a (cleanup-fault warning does not mask non-zero script exit — pins SPEC 7.4's "warnings do not affect outcome" rule on the cleanup-failure-warning branch under the script-error terminal across all three cleanup-fault seams × all three execution surfaces, complementing T-TMP-35d / 35e which cover only the cleanup-safety-warning branch on this terminal), T-TMP-42b (cleanup-fault warning does not mask abort — same parameterization as T-TMP-42a but on the abort terminal, complementing T-TMP-35g / 35h on the cleanup-safety-warning branch), T-ENV-21h, T-ENV-26b, T-ENV-26c, T-ENV-26d, T-ENV-26e, T-ENV-26f, T-ENV-26g, T-ENV-27b, T-ENV-27c, T-ENV-27d, T-ENV-27e. **Known gaps (not directly covered):** T-TMP-43 (mount-point non-detection inside `$LOOPX_TMPDIR` — privileged mount operations unavailable in standard CI), T-TMP-44 (host-crash cleanup non-guarantee — actual host crash unreproducible in CI), the cleanup-safety symlink-`unlink`-failure branch within creation-failure handling under `LOOPX_TEST_TMPDIR_FAULT=mode-secure-fail` (the partial directory created by `mkdtemp` is never a symlink, so cleanup-safety rule-2 dispatch is unreachable in that composition without an additional swap-to-symlink seam between identity capture and the cleanup-safety dispatch — see section 4.7's "Tmpdir Creation Sub-step Coverage" preamble; T-TMP-12e2 / T-TMP-12e3 cover the rule-4 recursive-remove and top-level-`lstat` branches respectively), T-SIG-29 (signal after tmpdir creation but before first child spawn — narrow window without a declared post-tmpdir-pre-spawn pause seam; see section 4.11 "Narrow Pre-iteration Windows (Known Gaps)"), T-SIG-30b / T-API-10j (CLI signal or programmatic abort concurrent with partial tmpdir creation failure — SPEC 7.4's "If a SIGINT/SIGTERM or `AbortSignal` abort arrives concurrently with a creation failure, the signal/abort wins and any partial directory is cleaned up under the same rules" clause; deterministic coverage requires a `LOOPX_TEST_TMPDIR_CREATION_PAUSE` pause sentinel with at least `after-mkdtemp-before-identity` and `creation-failure-observed-before-surface` window values — see section 4.11). |
+| 8.1 | Global Env Storage | T-ENV-01–15e, T-ENV-15f, T-ENV-15g, T-ENV-15h, T-ENV-15i, T-ENV-15i-single, T-ENV-15j, T-ENV-15k, T-ENV-15l, T-ENV-15m, T-ENV-15n, T-ENV-05a–05f, T-ENV-08a, T-ENV-21e, T-ENV-21f, T-ENV-21g, T-ENV-21h, T-ENV-25–25c, T-ENV-27, T-ENV-27a, T-ENV-27b, T-ENV-27c, T-ENV-27d, T-ENV-27e, T-CLI-22c, F-ENV-01–05, T-API-08k–08m, T-API-08k2, T-API-08l2, T-API-08m2, T-API-59, T-API-59a, T-API-59b, T-API-59c, T-API-59d (local `envFile` does not redirect global env-file lookup via `XDG_CONFIG_HOME` — extends the SPEC 8.1 "inherited environment" rule from the `RunOptions.env` tier (T-API-59 / T-API-59a / T-API-59b / T-API-59c) to the local-env-file tier on the `runPromise()` surface), T-API-59e (`HOME`-fallback counterpart to T-API-59d), T-API-59f (CLI `-e` parity for T-API-59d — closes the CLI surface for the SPEC 8.1 inherited-env rule on `XDG_CONFIG_HOME`), T-API-59g (CLI `-e` parity for T-API-59e — closes the CLI surface on `HOME`), T-API-59h (`run()` generator + `envFile` parity for T-API-59d — extends the SPEC 8.1 inherited-env rule to the `run()` × `envFile` × `XDG_CONFIG_HOME` cell under SPEC 9.1's lazy pre-iteration timing), T-API-59i (`run()` generator + `envFile` parity for T-API-59e — extends the same rule to the `run()` × `envFile` × `HOME` cell), T-API-73, T-API-73a, T-API-73b, T-API-73c, T-SUB-11a, T-SUB-14l, T-SUB-19a, T-TMP-12-global-env-unreadable, T-TMP-12-cli-global-env-unreadable, T-API-65r, T-API-68o, T-API-68q (`.return()` carve-out suppresses the SPEC 8.1 invalid-key warning emitted from the global env-file parse step — pins down that the parse step never runs), T-API-69n, T-API-69p (`.throw()` counterpart for the same global-env-file warning suppression), T-SIG-30, T-CLI-RUN-DASHDASH-10 (asserts the SPEC 8.1 invalid-key parser warning is **not** emitted when `--` is correctly rejected by the CLI parser before reaching env-file loading), T-CLI-RUN-DASHDASH-11 (target-then-flag-then-`--` symmetric coverage of the same SPEC 8.1 absence-of-invalid-key-warning observation). T-ENV-08a directly asserts the SPEC 8.1 whitespace-only-line rule (silently ignored, no warning, no bogus key). T-TMP-12-global-env-unreadable directly asserts the SPEC 8.1 unreadable-global-env-file → exit 1 rule and pins down that the failure surfaces before tmpdir creation per SPEC 7.1 step 2 ordering. T-API-65r / T-API-68o / T-API-69n / T-SIG-30 cover the same SPEC 8.1 unreadable-global-env-file failure mode across the abort-precedence (`runPromise` / `run` first-`next`), `.return()` carve-out, `.throw()` carve-out, and CLI signal-wins surfaces respectively. T-API-68q / T-API-69p cover the warning-side counterpart (malformed-but-readable global env file, parser warning suppressed). T-CLI-RUN-DASHDASH-10 / T-CLI-RUN-DASHDASH-11 use the SPEC 8.1 invalid-key warning (line `1BAD=…` in an on-disk file named `--`) as an externally observable side-effect that proves env-file loading was **not** attempted when `--` is correctly rejected as a usage error. |
+| 8.2 | Local Env Override | T-ENV-16–19, T-ENV-17a, T-ENV-25a, T-ENV-26, T-ENV-26a, T-ENV-26b, T-ENV-26c, T-ENV-26f, T-ENV-26g, T-CLI-22f, T-CLI-RUN-ORDER-05, T-TMP-29a, T-TMP-29d, T-TMP-29e, T-TMP-29f, T-TMP-29g, T-TMP-29h, T-TMP-29i, T-TMP-29j, T-TMP-29k, T-API-08p, T-API-08p2, T-API-08k2, T-API-20d2, T-API-20e2, T-API-21e2 (`run()` absolute `envFile` path used unchanged — generator-surface counterpart to T-API-21e on the `runPromise()` surface), T-API-59d (local `envFile` does not redirect global env-file lookup via `XDG_CONFIG_HOME`), T-API-59e (`HOME`-fallback counterpart to T-API-59d), T-API-59f (CLI `-e` parity on `XDG_CONFIG_HOME`), T-API-59g (CLI `-e` parity on `HOME`), T-API-59h (`run()` generator + `envFile` parity on `XDG_CONFIG_HOME`), T-API-59i (`run()` generator + `envFile` parity on `HOME`), T-API-65c, T-API-68p (`.return()` carve-out suppresses the SPEC 8.1 invalid-key warning emitted from the local-env-file parse step on the `envFile` path), T-API-69o (`.throw()` counterpart), T-SIG-20a |
+| 8.3 | Env Injection Precedence (incl. LOOPX_WORKFLOW_DIR, LOOPX_TMPDIR, PWD non-protocol) | T-ENV-20–24, T-ENV-20a, T-ENV-20b, T-ENV-21a, T-ENV-21b, T-ENV-21c, T-ENV-21d, T-ENV-21e, T-ENV-21f, T-ENV-21g, T-ENV-21h, T-ENV-24a, T-ENV-24a2, T-ENV-24a3, T-ENV-24a4, T-ENV-24a5, T-ENV-24a6 (LOOPX_DELEGATED four-tier ordinary-precedence), T-ENV-24b, T-ENV-26, T-ENV-26a, T-ENV-27, T-ENV-27a, T-EXEC-03a, T-EXEC-04–04c, T-DISC-39a, T-WFDIR-01, T-WFDIR-06, T-WFDIR-07, T-WFDIR-08, T-TMP-01, T-TMP-28, T-TMP-28a, T-TMP-28b, T-TMP-29a, T-TMP-29b, T-TMP-29c, T-TMP-29d, T-TMP-29e, T-TMP-29f, T-TMP-29g, T-TMP-29h, T-TMP-29i, T-TMP-29j, T-TMP-29k, T-TMP-30, T-TMP-31, T-PWD-01, T-PWD-02, T-PWD-03, T-PWD-04, T-PWD-07, T-PWD-08, T-CLI-RUN-INHERIT-01 (positive shell-env-prefix → inherited-env tier reaches the spawned script), T-API-50e, T-API-51a–51f, T-API-58, T-API-58a, T-API-59b, T-API-59c, T-API-59d, T-API-59e, T-API-59f, T-API-59g, T-API-59h, T-API-59i, T-API-60, T-API-60a, T-API-60b, T-API-60c, T-MOD-20a, T-DEL-07a |
+| 9.1 | run() (incl. pre-first-next carve-out, snapshot timing, abort precedence, pinned priority) | T-API-01–09c, T-API-09d, T-API-09e, T-API-08a–08e, T-API-08g–08m, T-API-08n1, T-API-08o–08v, T-API-08u2, T-API-08u3, T-API-08w–08y, T-API-08z, T-API-08z2–08z4, T-API-08aa, T-API-08ab, T-API-08t2–08t8, T-API-10–10c, T-API-10b2, T-API-10c3, T-API-10d, T-API-10e, T-API-10f, T-API-10f-throw, T-API-10g, T-API-10h, T-API-20d2, T-API-20h–20i, T-API-20j–20m, T-API-20j2, T-API-20p, T-API-20r, T-API-21e2 (`run()` absolute `envFile` path used unchanged — generator-surface counterpart to T-API-21e on the `runPromise()` surface), T-API-21f, T-API-21g, T-API-21k (`run()` combined relative `cwd` + relative `envFile` call-time resolution — generator-surface counterpart to T-API-21j), T-API-24c, T-API-24e, T-API-24g, T-API-24j, T-API-30–37, T-API-35a–35f, T-API-36a, T-API-50–50e, T-API-50g (concurrent `run()` generator isolation across two overlapping calls — `run()` counterpart to T-API-50f), T-API-51a–51f, T-API-52, T-API-52a, T-API-52b, T-API-52c, T-API-52e, T-API-52e2, T-API-53–55, T-API-53a–53d, T-API-54a–54c, T-API-55a, T-API-55c, T-API-55e (invalid `options` wrapper rejected as option-snapshot error before any spawn or tmpdir-creation — wrapper-shape validation runs before field-level processing, so the `maxIterations: 0` framing is not applicable to this case; `run()` surface), T-API-55f (invalid `options.signal` under `maxIterations: 0` — `run()` surface), T-API-55g (non-string `cwd` / `envFile` under `maxIterations: 0` — `run()` surface), T-API-55h (throwing `cwd` / `envFile` getters under `maxIterations: 0` — `run()` surface), T-API-56, T-API-56a, T-API-56b, T-API-56c, T-API-56d, T-API-56e, T-API-56f, T-API-56i (`run()`-surface representative coverage of SPEC 9.5 env-filtering and structural-shape-acceptance — generator-surface parity for the `runPromise()` matrix T-API-56 / T-API-56a / T-API-56b / T-API-56c / T-API-56g / T-API-56h), T-API-57, T-API-57a, T-API-57b, T-API-57c, T-API-57f, T-API-57f2, T-API-57g, T-API-57h, T-API-57i, T-API-58, T-API-58a, T-API-59, T-API-59a, T-API-59b, T-API-59c, T-API-59h (`run()` generator + `envFile` does not redirect global env-file lookup via `XDG_CONFIG_HOME` — extends the SPEC 8.1 inherited-env rule to the `run()` × `envFile` cell under SPEC 9.1's lazy pre-iteration timing), T-API-59i (`HOME`-fallback counterpart to T-API-59h), T-API-60, T-API-60a, T-API-60b, T-API-60c, T-API-61–62g, T-API-61a–61c, T-API-61f, T-API-61h, T-API-61i, T-ENV-26f, T-ENV-26g, T-ENV-27d, T-ENV-27e, T-API-62a–62f, T-API-62f3, T-API-62h, T-API-62h3, T-API-62h5, T-API-62h7, T-API-62h9, T-API-62h10, T-API-62i, T-API-62i3, T-API-63, T-API-64, T-API-64a, T-API-64a2 (`run()` own-property duck-signal acceptance — generator-surface counterpart to T-API-64a, complementing T-API-64n on the prototype-inherited axis), T-API-64b–64e, T-API-64f, T-API-64h, T-API-64i, T-API-64i3, T-API-64j, T-API-64k, T-API-64k3, T-API-65–66, T-API-65a–65e, T-API-65a2, T-API-65f, T-API-65h, T-API-65i, T-API-65j, T-API-65k–65o, T-API-65q, T-API-65r, T-API-65s, T-API-65t, T-API-65u, T-API-65w, T-API-66a, T-API-66b, T-API-67, T-API-67a–67c, T-API-68, T-API-68a–68e, T-API-68f, T-API-68g, T-API-68h, T-API-68i, T-API-68j, T-API-68k, T-API-68l, T-API-68m, T-API-68n, T-API-68o, T-API-68p (`.return()` carve-out warning suppression: local env-file), T-API-68q (`.return()` carve-out: global env-file), T-API-68r (`.return()` carve-out: workflow `package.json` parameterized over four SPEC 3.2 branches), T-API-69, T-API-69a–69c, T-API-69d, T-API-69e, T-API-69f, T-API-69g, T-API-69h, T-API-69i, T-API-69j, T-API-69k, T-API-69l, T-API-69m, T-API-69n, T-API-69o (`.throw()` carve-out warning suppression: local env-file), T-API-69p (`.throw()`: global env-file), T-API-69q (`.throw()`: workflow `package.json`), T-API-71, T-API-71a, T-API-73, T-API-73b, T-EXEC-15c, T-LOOP-46, T-PARSE-20a, T-TERM-02c (programmatic `run()` racing abort vs. consumer `.throw()` — abort-first wins), T-TERM-02d (programmatic `run()` racing consumer `.throw()` vs. abort — `.throw()`-first surfaced outcome is not abort), T-TMP-08c (concurrent `run()` generator tmpdir isolation — generator-surface counterpart to T-TMP-08a / T-TMP-08b under the SPEC 9.1 lazy-snapshot timing), T-TMP-11a (`run()` generator zero-iteration tmpdir non-creation — generator-surface counterpart to T-TMP-11), T-TMP-12b, T-TMP-12g (`run()` programmatic version-check-before-tmpdir-creation across four SPEC 3.2 branches), T-TMP-15b, T-TMP-16b, T-TMP-16e, T-TMP-16f, T-TMP-16i (`run()` cleanup on bare-name `goto` missing-script), T-TMP-16j (`run()` counterpart for name-restriction-violation `goto` cleanup), T-TMP-19–22, T-TMP-22a, T-TMP-22b, T-TMP-22c, T-TMP-22d, T-TMP-22e, T-TMP-22f, T-TMP-24c, T-TMP-24d, T-TMP-26, T-TMP-26-temp, T-TMP-26-tmp, T-TMP-35b, T-TMP-35e, T-TMP-36b, T-TMP-38a2 (programmatic `run()` cleanup idempotence on the mid-loop `.return()`-first × abort-second race — symmetric counterpart to T-TMP-38a on the inverted observation order), T-TMP-38c (programmatic `run()` cleanup idempotence — abort observed first, racing `.throw()` during cleanup-start), T-TMP-38d2 (programmatic `run()` cleanup idempotence on the post-final-yield `.throw()`-first × abort-second race — symmetric counterpart to T-TMP-38d on the inverted observation order), T-API-64n (prototype-inherited duck-signal acceptance — `run()`), T-TYPE-04, T-TYPE-06–07. T-API-62f2 is observational only (descriptor-trap invocation is implementation-defined; not directly traced). T-API-62f3 / T-API-62h9 / T-API-52e / T-API-52e2 are strict conformance pins on the Proxy `get`-trap axis per SPEC §9.5's normative `[[Get]]`-semantics-exactly-once rule. |
+| 9.2 | runPromise() | T-API-08f, T-API-08k2, T-API-08l2, T-API-08m2, T-API-08n, T-API-08p2, T-API-10c2, T-API-10d-promise, T-API-10e-promise, T-API-11–14l, T-API-14b2–14b4, T-API-14j2–14j8, T-API-14k2, T-API-14k3, T-API-14m–14o, T-API-14p, T-API-14p2–14p4, T-API-14q, T-API-14r, T-API-14a–14a3, T-API-19a, T-API-20e2, T-API-20n, T-API-20o, T-API-20p2, T-API-20p3, T-API-20q, T-API-20q2, T-API-20s, T-API-21h, T-API-21i, T-API-21j, T-API-24d, T-API-59d (local `envFile` does not redirect global env-file lookup via `XDG_CONFIG_HOME` — runPromise surface), T-API-59e (`HOME`-fallback counterpart to T-API-59d), T-API-24f, T-API-24h, T-API-24i, T-API-25–25b, T-API-38–48, T-API-45a, T-API-47a–47b, T-API-48a, T-API-44a–44c, T-API-52d, T-API-52e, T-API-52e2, T-API-55b, T-API-55d, T-API-55e (invalid `options` wrapper rejected as option-snapshot error before any spawn or tmpdir-creation — wrapper-shape validation runs before field-level processing, so the `maxIterations: 0` framing is not applicable; `runPromise()` surface), T-API-55f (invalid `options.signal` under `maxIterations: 0` — `runPromise()` surface), T-API-55g (non-string `cwd` / `envFile` under `maxIterations: 0` — `runPromise()` surface), T-API-55h (throwing `cwd` / `envFile` getters under `maxIterations: 0` — `runPromise()` surface), T-API-56c, T-API-56d, T-API-56e, T-API-56f, T-API-57d, T-API-57e, T-API-60, T-API-61d, T-API-61e, T-API-61g, T-API-61h, T-API-61j, T-API-62g, T-API-62h2, T-API-62h4, T-API-62h6, T-API-62h8, T-API-62h9, T-API-62h11, T-API-62i2, T-API-62i4, T-API-63a, T-API-64g, T-API-64h2, T-API-64i2, T-API-64i4, T-API-64j2, T-API-64k2, T-API-64k3, T-API-64n2 (prototype-inherited duck-signal acceptance — `runPromise()`), T-API-65–65e, T-API-65a2, T-API-65g–65j, T-API-65p, T-API-65r, T-API-65s, T-API-65t, T-API-65u, T-API-65v, T-API-67d–67g, T-API-70, T-API-72, T-API-73a, T-API-73c, T-ENV-05f, T-LOOP-45, T-TMP-12c, T-TMP-12h (`runPromise()` programmatic version-check-before-tmpdir-creation across four SPEC 3.2 branches), T-TMP-13a, T-TMP-14a, T-TMP-15a, T-TMP-16b, T-TMP-16c, T-TMP-16d, T-TMP-16h (`runPromise()` cleanup on bare-name `goto` missing-script), T-TMP-16j (`runPromise()` counterpart for name-restriction-violation `goto` cleanup), T-TMP-27, T-TMP-27a (asynchronous tmpdir creation post-return — pins SPEC 9.2's "`LOOPX_TMPDIR` itself is created asynchronously after return"), T-TMP-27-temp, T-TMP-27-tmp, T-TMP-29f, T-TMP-29g, T-TMP-29h, T-TMP-35a, T-TMP-35d, T-TMP-36a, T-PARSE-20a, T-TYPE-05–07 |
+| 9.3 | API Error Behavior | T-API-10b2, T-API-10c2, T-API-10c3, T-API-15–19, T-API-19a, T-API-20a–20s, T-API-20d2, T-API-20e2, T-API-20p2, T-API-20p3, T-API-20q2, T-API-21c–21d, T-API-57, T-API-57a, T-API-57c, T-API-57h, T-API-57i, T-ENV-26f, T-ENV-27d, T-API-64, T-API-64h, T-API-64i, T-API-64i3, T-API-64i4, T-API-64j, T-API-65–65e, T-API-65a2, T-API-65f, T-API-65g, T-API-65h, T-API-65i, T-API-65j, T-API-65k–65o, T-API-65p, T-API-65q, T-API-65r, T-API-65s, T-API-65t, T-API-65u, T-API-65v, T-API-65w, T-API-66a, T-API-66b, T-API-67–67g, T-API-64h2, T-API-64i2, T-API-64j2, T-ENV-05f, T-TERM-01 (programmatic `runPromise()` racing non-zero exit vs. abort — surfaced rejection reflects first-observed trigger), T-TERM-02 (programmatic `run()` racing abort vs. consumer `.return()`), T-TERM-02c (programmatic `run()` racing abort vs. consumer `.throw()` — abort-first wins), T-TERM-02d (programmatic `run()` racing consumer `.throw()` vs. abort — `.throw()`-first surfaced outcome is not abort), T-TERM-04 (programmatic `runPromise()` racing child spawn failure vs. abort), T-TMP-12b (`run()` tmpdir creation failure → throw on first `next()`), T-TMP-12c (`runPromise()` tmpdir creation failure → reject), T-TMP-12d / T-TMP-12e (programmatic-surface variants of identity-capture / mode-secure sub-step failures via `LOOPX_TEST_TMPDIR_FAULT`), T-TMP-12d2 / T-TMP-12e2 / T-TMP-12e3 (programmatic-surface variants of cleanup-failure-during-creation-failure-handling via the compound `identity-capture-fail-rmdir-fail` seam value, the `mode-secure-fail` × `recursive-remove-fail` seam composition, and the `mode-secure-fail` × `lstat-fail` seam composition), T-TMP-15a, T-TMP-15b, T-TMP-16b, T-TMP-16c, T-TMP-16d, T-TMP-16e, T-TMP-16f, T-TMP-16h (`runPromise()` cleanup on bare-name `goto` missing-script — cleanup-ordering counterpart on the bare-name lookup path), T-TMP-16i (`run()` counterpart), T-TMP-24a, T-TMP-24c, T-TMP-24d, T-TMP-38c (programmatic `run()` cleanup idempotence — abort observed first, racing `.throw()` during cleanup-start), T-TMP-38d (programmatic `run()` cleanup idempotence on the **post-final-yield abort × `.throw()` race** — pins the warning-cardinality axis of SPEC 9.3's abort-after-final-yield rule on a warning-emitting cleanup branch, complementing T-API-66b / T-API-66e which cover the outcome axis on a non-warning-emitting fixture), T-TMP-38d2 (symmetric counterpart on the inverted observation order — **post-final-yield `.throw()` observed first, racing abort during cleanup-start** — closes the `.throw()`-first half of the same warning-cardinality axis under SPEC 7.2's first-observed-wins residual rule), T-TMP-38e (programmatic `runPromise()` cleanup idempotence — child spawn failure concurrent with abort — warning-cardinality axis on the spawn-failure × abort race covered for outcome by T-TERM-04), T-TMP-42a (cleanup-failure warning branch × non-zero script exit terminal — pins SPEC 9.3's "cleanup warnings do not mask the original rejection reason" rule on the cleanup-failure-warning branch, complementing T-TMP-35d / 35e on the cleanup-safety-warning branch), T-TMP-42b (cleanup-failure warning branch × abort terminal — same parameterization as T-TMP-42a but on the abort terminal, complementing T-TMP-35g / 35h on the cleanup-safety-warning branch). T-API-10c2 / T-API-10c3 directly assert the SPEC 9.3 abort precedence × `maxIterations: 0` rule; T-API-64j / T-API-64j2 directly assert the SPEC 9.5 "missing / non-boolean `aborted` is non-compatible" rule. **Known gaps (not directly covered):** T-API-10i — programmatic abort delivered during pre-iteration but before first child spawn (note: T-API-10b2 covers the **separate** abort-after-call-before-first-`next()` window — that window is not the gap because no `next()` has been called yet, so timing is fully under the test's control without a harness seam); deterministic coverage of T-API-10i specifically would still require a programmatic pre-iteration sentinel / delay seam. T-API-10j — programmatic abort concurrent with partial tmpdir creation failure (SPEC 7.4's "If a SIGINT/SIGTERM or `AbortSignal` abort arrives concurrently with a creation failure, the signal/abort wins ..." clause on the programmatic surface); deterministic coverage requires a `LOOPX_TEST_TMPDIR_CREATION_PAUSE` pause sentinel — see section 4.11 "Narrow Pre-iteration Windows (Known Gaps)". |
+| 9.4 | output() and input() (script-side) | *(Same as 6.4/6.5, plus T-TYPE-08 for compile-time type-surface verification)* |
+| 9.5 | Types / RunOptions (incl. RunOptions.env) | T-API-07–08, T-API-07a, T-API-07b, T-API-07c, T-API-08b–08r, T-API-08n1, T-API-08v, T-API-08w–08y, T-API-10–10c, T-API-10b2, T-API-10c2, T-API-10c3, T-API-10d, T-API-10d-promise, T-API-10e, T-API-10e-promise, T-API-10f, T-API-10f-throw, T-API-10g, T-API-10h, T-API-14b2–14b4, T-API-14f–14h, T-API-14l, T-API-14m–14o, T-API-20d–20e, T-API-20d2, T-API-20e2, T-API-21–21b, T-API-21e, T-API-21e2 (`run()` absolute `envFile` path used unchanged — generator-surface counterpart to T-API-21e), T-API-21f, T-API-21g, T-API-21h, T-API-21i, T-API-21j, T-API-21k (`run()` combined relative `cwd` + relative `envFile` call-time resolution — generator-surface counterpart to T-API-21j on the joint axis), T-API-22–25b, T-API-23a, T-API-24a–24b, T-API-24c, T-API-24d, T-API-24e, T-API-24f, T-API-24g, T-API-24h, T-API-24i, T-API-24j, T-API-47b, T-API-50–50e, T-API-50f (concurrent isolation across two overlapping `runPromise()` calls — pins ADR-0004's "no racy global `process.env` mutation" motivation), T-API-50g (`run()` generator counterpart for the same concurrent-isolation contract), T-API-51a–51f, T-API-52, T-API-52a, T-API-52b, T-API-52c, T-API-52d, T-API-52e, T-API-52e2, T-API-53–55, T-API-53a–53d, T-API-54a–54c, T-API-55a, T-API-55b, T-API-55c, T-API-55d, T-API-55e (invalid `options` wrapper rejected as option-snapshot error — wrapper-shape validation runs before field-level processing, so the `maxIterations: 0` framing is not applicable to this case; both surfaces), T-API-55f (invalid `options.signal` under `maxIterations: 0` — both surfaces), T-API-55g (non-string `cwd` / `envFile` under `maxIterations: 0` — both surfaces), T-API-55h (throwing `cwd` / `envFile` getters under `maxIterations: 0` — both surfaces), T-API-56, T-API-56a, T-API-56b, T-API-56c (null-prototype env), T-API-56d (symbol-keyed throwing-getter ignored), T-API-56e (non-enumerable throwing-getter ignored), T-API-56f (inherited non-string-value ignored), T-API-56g (class-instance env accepted — non-plain-object positive coverage), T-API-56h (`Map` env accepted but contributes zero own enumerable string-keyed entries), T-API-56i (`run()`-surface representative coverage parameterized over the five SPEC 9.5 sub-rules — inherited / symbol-keyed / non-enumerable filtering, null-prototype acceptance, class-instance / `Map` structural-shape acceptance — closing the surface-parity gap relative to the `runPromise()` matrix T-API-56 / 56a / 56b / 56c / 56g / 56h), T-API-57, T-API-57a, T-API-57b, T-API-57c, T-API-57d, T-API-57e, T-API-57f, T-API-57f2, T-API-57g, T-API-57h, T-API-57i, T-API-58, T-API-58a, T-API-59, T-API-59a, T-API-59b, T-API-59c, T-API-59d (local `envFile` does not redirect global env-file lookup via `XDG_CONFIG_HOME` — extends the SPEC 8.1 "inherited environment" rule to the local-env-file tier under SPEC 9.5's `envFile` option semantics), T-API-59e (`HOME`-fallback counterpart to T-API-59d), T-API-59h (`run()` generator-surface counterpart to T-API-59d under SPEC 9.5's `envFile` option semantics × SPEC 9.1's lazy pre-iteration timing), T-API-59i (`HOME`-fallback counterpart to T-API-59h), T-API-60, T-API-60a, T-API-60b, T-API-60c, T-API-61–67, T-API-61a–61e, T-API-61f, T-API-61g, T-API-61h, T-API-61i (null-prototype options on `run`), T-API-61j (null-prototype options on `runPromise`), T-API-61k (class-instance outer options accepted — non-plain-object positive coverage on the outer `options` axis), T-API-61l (`Map` outer options accepted but contributes zero option fields — no auto-enumerate-conceptual-entries on the outer `options` axis), T-API-62a–62g, T-API-62f3, T-API-62h, T-API-62h2, T-API-62h3, T-API-62h4, T-API-62h5, T-API-62h6, T-API-62h7, T-API-62h8, T-API-62h9, T-API-62h10, T-API-62h11, T-API-62i, T-API-62i2, T-API-62i3, T-API-62i4, T-API-63, T-API-63a, T-API-64–64e, T-API-64a2 (`run()` own-property duck-signal acceptance — generator-surface counterpart to T-API-64a's `runPromise()` test, closing the {own-property / prototype-inherited} × {`run()` / `runPromise()`} duck-signal acceptance matrix together with T-API-64n / T-API-64n2), T-API-64f, T-API-64g, T-API-64h, T-API-64h2, T-API-64i, T-API-64i2, T-API-64i3, T-API-64i4, T-API-64j, T-API-64j2, T-API-64k, T-API-64k2, T-API-64k3, T-API-64n, T-API-64n2 (prototype-inherited `aborted` / `addEventListener` accepted — pins SPEC 9.5's "expose" wording against own-property-only readings of the duck-signal contract), T-API-65–66, T-API-65a–65e, T-API-65a2, T-API-65f, T-API-65g, T-API-65h, T-API-65i, T-API-65j, T-API-65k–65o, T-API-65p, T-API-65q, T-API-65r, T-API-65s, T-API-65t, T-API-65u, T-API-65v, T-API-65w, T-API-66a, T-API-66b, T-API-67a–67g, T-API-68–69c, T-API-68f, T-API-68g, T-API-68h, T-API-68i, T-API-68j, T-API-68k, T-API-68l, T-API-68m, T-API-68n, T-API-68o, T-API-68p, T-API-68q, T-API-68r, T-API-69d, T-API-69e, T-API-69f, T-API-69g, T-API-69h, T-API-69i, T-API-69j, T-API-69k, T-API-69l, T-API-69m, T-API-69n, T-API-69o, T-API-69p, T-API-69q, T-API-70, T-API-71, T-API-71a, T-API-72, T-DISC-48a, T-SYM-04a, T-SYM-04b, T-SYM-04c, T-SYM-06a, T-TMP-08c (concurrent `run()` generator tmpdir isolation under SPEC 9.5 `RunOptions.env` per-run injection), T-TMP-11a (`run()` `maxIterations: 0` zero-iteration tmpdir non-creation — pins the SPEC 9.5 "No `LOOPX_TMPDIR` is created under `maxIterations: 0`" rule on the generator surface), T-TMP-29b, T-TMP-29c, T-TMP-29f, T-TMP-29g, T-TMP-29h, T-TMP-29i, T-TMP-29j, T-TMP-29k, T-TYPE-01–08. T-API-62f2 is observational only (descriptor-trap invocation is implementation-defined; not directly traced). T-API-62f3 / T-API-62h9 / T-API-52e / T-API-52e2 are strict conformance pins on the Proxy `get`-trap axis per SPEC §9.5's normative `[[Get]]`-semantics-exactly-once rule. |
+| 10.1 | Source Detection | T-INST-01–01a, T-INST-02–08f, T-INST-05a, T-INST-08g, T-INST-08g2, T-INST-08h, T-INST-08i, T-INST-08j, T-INST-08k, T-INST-08l, T-INST-08m, T-INST-41, T-INST-42k, T-INST-42l |
+| 10.2 | Source Type Details | T-INST-52d, T-INST-54d, T-INST-56b, T-INST-57c, T-INST-81–89, T-INST-83a, T-INST-83b, T-INST-85a–85b, T-INST-86a, T-INST-87 |
+| 10.3 | Workflow Classification | T-INST-42m, T-INST-42n, T-INST-50–56, T-INST-50a–50b, T-INST-52a, T-INST-52c, T-INST-52d, T-INST-53a–53c, T-INST-54a–54d, T-INST-55a–55t, T-INST-56a–56i, T-INST-57b, T-INST-60o, T-INST-63e, T-INST-64, T-INST-64b, T-INST-64e, T-INST-80g, T-INST-83a, T-INST-83b, T-INST-85b |
+| 10.4 | Install-time Validation | T-INST-42m, T-INST-42n, T-INST-52a–52d, T-INST-55f, T-INST-55g, T-INST-55h, T-INST-55i, T-INST-55j, T-INST-55k, T-INST-55l, T-INST-55m, T-INST-55n, T-INST-55o, T-INST-55p, T-INST-55q, T-INST-55r, T-INST-55s, T-INST-55t, T-INST-61–64, T-INST-62a, T-INST-63a–63e, T-INST-63f, T-INST-63g, T-INST-64a–64e, T-INST-72a, T-INST-73a, T-INST-74a, T-INST-75a, T-INST-76a, T-INST-80h–80j, T-INST-60a, T-INST-60e, T-INST-60g, T-INST-60h, T-INST-60n |
+| 10.5 | Collision Handling | T-INST-65–71, T-INST-67a, T-INST-70a–70d, T-INST-70e, T-INST-71a, T-INST-97c, T-INST-60c, T-INST-60k, T-INST-60l, T-INST-60p, T-INST-120c, T-INST-120d (`-y --no-install` replacement — explicit-opt-out branch of the `-y` × auto-install matrix) |
+| 10.6 | Version Checking on Install | T-INST-72–76, T-INST-72a, T-INST-73a, T-INST-74a, T-INST-75a, T-INST-76a, T-INST-97b, T-INST-111b, T-VER-12–13, T-VER-12a–12c, T-VER-13a, T-VER-13b, T-VER-13c, T-VER-13d, T-VER-15, T-VER-15a, T-VER-15d, T-VER-17, T-VER-22, T-VER-23a, T-INST-80d–80f, T-INST-54b, T-INST-54d, T-INST-60b, T-INST-60f, T-INST-60i, T-INST-60j, T-INST-60q–60s, T-INST-120b, T-DEL-25 |
+| 10.7 | Install Atomicity | T-INST-55r, T-INST-55s, T-INST-63e, T-INST-77–80j, T-INST-80c2, T-INST-112d. **Staging-failure tests** (T-INST-79, T-INST-80b, T-INST-97a) use the `LOOPX_TEST_INSTALL_FAULT=staging-fail:<workflow>` seam from section 1.4 to drive the staging-failure outcome deterministically; they do not depend on filesystem-permission tricks (mode-000 fixtures) and are runnable under any user. **Known gap (not directly covered):** T-INST-79a — removal of the implementation-private temporary staging directory itself is not observed; current tests assert the externally visible `.loopx/`-unchanged contract. |
+| 10.8 | Selective Workflow Installation | T-INST-57–60, T-INST-57a–57c, T-INST-59a–59b, T-INST-60a–60p, T-INST-60q–60s, T-INST-64c, T-INST-110f, T-INST-55n, T-INST-55t |
+| 10.9 | Common Rules (stage-then-commit leaves `.loopx/` unchanged on pre-commit failure) | T-INST-90, T-INST-92, T-INST-92a, T-INST-92b, T-INST-92c, T-INST-93–97b, T-INST-97a, T-INST-97a2, T-INST-112d. **Staging-failure path uses the `LOOPX_TEST_INSTALL_FAULT=staging-fail:<workflow>` seam from section 1.4** (see 10.7 row for rationale). **Known gap (not directly covered):** T-INST-79a — removal of the implementation-private temporary staging directory itself is not observed; current tests assert the externally visible `.loopx/`-unchanged contract. |
+| 10.10 | Auto-install Workflow Dependencies | T-EXEC-15a, T-EXEC-15b, T-EXEC-15c, T-INST-44a, T-INST-44b, T-INST-44c, T-INST-44d, T-INST-44e, T-INST-44f (no short alias for `--no-install` — parser side; SPEC 4.2 "No short form" pinned alongside T-INST-41's help-text-side assertion (f)), T-INST-80c2, T-INST-110, T-INST-110a, T-INST-110b, T-INST-110c, T-INST-110d, T-INST-110e, T-INST-110f, T-INST-111, T-INST-111a, T-INST-111b, T-INST-111c, T-INST-112, T-INST-112a, T-INST-112a2 (positive interaction between SPEC 10.11 source-symlink materialization and SPEC 10.10's regular-file safeguard branch — source `.gitignore` is a symlink to a regular file, materialized as a regular file, safeguard takes the regular-file branch and `npm install` proceeds), T-INST-112b, T-INST-112c, T-INST-112d, T-INST-112e (directory pre-existing `.gitignore` → safeguard failure), T-INST-112f (`--no-install` short-circuits the safeguard before `lstat` dispatch even when entry is non-regular), T-INST-112g (symlink pre-existing `.gitignore` → safeguard failure across regular-file-target / broken / cyclic sub-cases via the `gitignore-replace-with-symlink:` seam from section 1.4), T-INST-112h (top-level `.gitignore` `lstat` failure other than `ENOENT` via the `gitignore-lstat-fail:` seam), T-INST-112i (FIFO pre-existing `.gitignore` → safeguard failure via the `gitignore-replace-with-fifo:` seam), T-INST-112j (socket pre-existing `.gitignore` → safeguard failure via the `gitignore-replace-with-socket:` seam), T-INST-112k (regular but unreadable pre-existing `.gitignore` — permission-non-inspection axis via the `gitignore-make-unreadable:` seam), T-INST-113, T-INST-113a, T-INST-113b, T-INST-113c, T-INST-113c2, T-INST-113d, T-INST-113d2, T-INST-113e, T-INST-113f, T-INST-113g, T-INST-114, T-INST-114a, T-INST-114b, T-INST-114c, T-INST-114d (mixed safeguard / non-zero-exit / spawn-failure aggregate report), T-INST-115, T-INST-115a, T-INST-115b, T-INST-116, T-INST-116a, T-INST-116b, T-INST-116b2 (SIGTERM-axis remaining-workflows-not-processed parity for T-INST-116b), T-INST-116c, T-INST-116d, T-INST-116d2 (SIGTERM-axis partial-`node_modules/`-not-cleaned parity for T-INST-116d), T-INST-116e, T-INST-116f, T-INST-116g, T-INST-116h (signal during auto-install pass — `between-workflows-after-first` ordinal no-active-child window via the `LOOPX_TEST_AUTOINSTALL_PAUSE` seam), T-INST-116h2 (SIGTERM-axis parity for T-INST-116h), T-INST-116i (`pre-spawn-first` ordinal window), T-INST-116i2 (SIGTERM-axis parity for T-INST-116i), T-INST-116j (`post-exit-first` ordinal window with SIGTERM parity), T-INST-116j2 (`post-exit-first` ordinal window composed with non-zero npm exit and SIGINT — closes the post-npm-child-exit no-active-child window when the aggregate-report accumulator already holds an npm-non-zero entry), T-INST-116j3 (SIGTERM-axis parity for T-INST-116j2 — closes the SPEC 10.10 SIGINT/SIGTERM parity for the post-exit-first × non-zero-npm-exit composed window), T-INST-116k (`post-safeguard-failure-first` ordinal window with aggregate-report-suppression-after-accumulated-failure sub-case via PAUSE+FAULT seam composition; FAULT applied to all three workflows so the test is order-independent), T-INST-116k2 (SIGTERM-axis parity for T-INST-116k), T-INST-116m (`post-spawn-failure-first` ordinal window with aggregate-report-suppression for the `npm-install-spawn-failure` accumulator state — closes the no-active-child × suppression contract on the structurally distinct spawn-failure failure class via the `npm-spawn-fail:` FAULT seam composed with the new `post-spawn-failure-first` PAUSE seam), T-INST-116m2 (SIGTERM-axis parity for T-INST-116m), T-INST-116l (the **already-emitted carve-out** half of SPEC 10.10's signal-termination clause — signal observed after the aggregate report has been written to stderr but before loopx's process exits — covered via the `post-aggregate-report` ordinal value of the section 1.4 `LOOPX_TEST_AUTOINSTALL_PAUSE` seam, with explicit no-rollback assertions on committed workflow files and already-created auto-install side effects to match the no-active-child signal-window tests T-INST-116h / 116i / 116j / 116k), T-INST-116l2 (SIGTERM-axis parity for T-INST-116l — pins the SPEC 10.10 already-emitted carve-out for SIGTERM as well as SIGINT), T-INST-117, T-INST-117a, T-INST-117b (retry-after-auto-install-failure end-to-end via `loopx install -y <source>` — pins SPEC 10.10's explicit retry/remediation path beyond T-INST-117 / T-INST-117a's no-rollback contract and T-INST-120's pre-seed-based replacement-freshness contract), T-INST-118, T-INST-118a, T-INST-118b, T-INST-118c, T-INST-119, T-INST-119a, T-INST-119a-stderr (real-time stderr passthrough), T-INST-119b, T-INST-120, T-INST-120a, T-INST-120b, T-INST-120c (replacement-without-`package.json` × `-y` × auto-install-trigger boundary), T-INST-120d (`-y --no-install` replacement — pins the explicit-opt-out branch where the replacement *would* trigger auto-install but `--no-install` suppresses both `npm install` and `.gitignore` synthesis; complements T-INST-120c's trigger-condition-failure branch), T-VER-15c, T-VER-15d. T-INST-80c2 directly asserts SPEC 10.10's "commit phase completes successfully" gating rule for the post-commit auto-install pass. T-INST-112h / T-INST-112i / T-INST-112j / T-INST-112k close the previously-tracked residual gaps for the `lstat`-failure branch, the FIFO / socket instances of SPEC 10.10's non-regular `.gitignore` enumeration, and the permission-non-inspection axis of the regular-file branch. T-INST-116h / T-INST-116i / T-INST-116j / T-INST-116k close the **suppression** half of SPEC 10.10's signal-termination clause for the no-active-child signal sub-windows (formerly P-0004-02); T-INST-116m extends the suppression-half coverage to the `npm-install-spawn-failure` accumulator state (a structurally distinct failure class from the safeguard-failure and non-zero-npm-exit accumulator states already pinned by T-INST-116k and T-INST-116j2 respectively); T-INST-116l closes the complementary **already-emitted carve-out** half. T-INST-116h2 / T-INST-116i2 / T-INST-116k2 / T-INST-116l2 / T-INST-116m2 close the SPEC 10.10 SIGINT/SIGTERM parity for these no-active-child windows on the SIGTERM axis (T-INST-116j is already SIGTERM, T-INST-116j2 is SIGINT after non-zero npm exit, T-INST-116j3 closes the remaining post-exit-first × non-zero-npm-exit × SIGTERM corner, and T-INST-116m2 closes the post-spawn-failure-first × spawn-failure-accumulator × SIGTERM corner). |
+| 10.11 | Install Source Symlinks | T-INST-55f, T-INST-55g, T-INST-55h, T-INST-55i, T-INST-55j, T-INST-55k, T-INST-55l, T-INST-55m, T-INST-55n, T-INST-55o, T-INST-55p, T-INST-55q, T-INST-55r, T-INST-55s, T-INST-55t. Each test is parameterized across git and tarball sources per SPEC 10.2 / 10.11. Discovery-policy parity with SPEC 5.1 is also covered indirectly by T-INST-55f / T-INST-55g (workflow-name and script-name derivation from the symlink entry's own name). T-INST-55j / T-INST-55k cover the "Symlinked non-script files or directories ... are likewise materialized" rule for non-script content; T-INST-55l covers the rejection rule for broken / cyclic / out-of-source non-script symlinks; T-INST-55m covers the rejection rule for top-level workflow-directory symlinks resolving outside the install source root; T-INST-55n covers the SPEC 10.11 + SPEC 10.3 + SPEC 10.8 interaction for symlink targets inside the install source root but outside the selected workflow (legitimate cross-workflow-to-source-root references); T-INST-55o covers install-time symlink-alias-name validation (the alias's own name is validated, not the target's basename — negative path); T-INST-55p covers install-time symlink entry-type-policy parity with runtime (symlink to file is not a workflow, symlink to directory is not a script — including the SPEC 10.11 materialization rule for symlinked-non-script-content for the script-symlink-to-directory sub-case); T-INST-55q covers install-time symlink-alias-name validation positive path (valid alias accepted regardless of invalid target basename); T-INST-55r covers install-time same-base-name script-collision detection when one of the colliding scripts is a symlink (parity with runtime T-DISC-40e); T-INST-55s covers the SPEC 10.11 broken / cycle rejection rule for top-level workflow-directory symlinks (companion to T-INST-55m which covers the out-of-source class for the same code path); T-INST-55t covers SPEC 10.11's selective-validation interaction with SPEC 10.3 / 10.8 — bad symlinks in source-root support directories are ignored under both full and `-w` invocations. T-INST-112a2 covers the positive interaction between SPEC 10.11's source-symlink materialization and SPEC 10.10's `.gitignore` safeguard regular-file branch — a source `.gitignore` symlink to a regular file is materialized as a regular file at the workflow's `.gitignore` path, the safeguard's `lstat` observes a regular file, and `npm install` proceeds normally; a buggy implementation that materialized source symlinks for script files but missed `.gitignore` would commit a symlink at the workflow's `.gitignore` path and the safeguard would surface a failure. |
+| 11.1 | Top-Level Help | T-CLI-02–06, T-CLI-07e–07g, T-CLI-07j, T-CLI-28, T-CLI-39, T-CLI-61, T-CLI-65, T-CLI-90–91, T-CLI-01b, T-CLI-TOP-DASHDASH-01 (top-level `loopx --` rejection — top-level parser surface, paired with the top-level help tests) |
+| 11.2 | Run Help | T-CLI-40–43a, T-CLI-40a, T-CLI-40b, T-CLI-62, T-CLI-67–78, T-CLI-69a, T-CLI-70a, T-CLI-84, T-CLI-92–95, T-CLI-101–102, T-CLI-101a, T-CLI-104–106, T-CLI-104a–104e, T-CLI-120–122, T-CLI-120a, T-CLI-120b, T-CLI-123, T-CLI-123a, T-CLI-124, T-CLI-124a, T-CLI-125, T-CLI-126, T-CLI-RUN-DASHDASH-04, T-CLI-RUN-DASHDASH-05, T-CLI-RUN-DASHDASH-08, T-CLI-RUN-DASHDASH-09, T-CLI-RUN-NAMEVAL-04, T-CLI-RUN-NAMEVAL-05, T-DISC-10d–10g, T-DISC-15b, T-DISC-38, T-DISC-40b–40e, T-DISC-40g–40i, T-DISC-40j, T-DISC-40k, T-TMP-12-cli-help-with-unknown (run-help short-circuit creates no `LOOPX_TMPDIR`), T-TMP-12-cli-help-with-dashdash (long-form `--help` with `--` token, same no-tmpdir guarantee), T-VER-19, T-VER-19a–19c |
+| 11.3 | Install Help | T-INST-41 (now strengthened with assertion (f) — install help text does not advertise any short alias for `--no-install`), T-INST-42, T-INST-41a, T-INST-42a–42l, T-INST-44b, T-INST-44c, T-INST-44d, T-INST-44e, T-INST-49a–49g, T-INST-DASHDASH-03, T-INST-DASHDASH-04 |
+| 12 | Exit Codes | T-EXIT-01–17. **Additional SPEC 12 exit-code sub-paths covered elsewhere by direct category tests (listed here for traceability rather than duplicated under T-EXIT-*):** tmpdir-creation failure → exit 1 covered by T-TMP-12a (CLI) / T-TMP-12b (`run()`) / T-TMP-12c (`runPromise()`); child launch / spawn failure after tmpdir creation → exit 1 covered by T-DISC-42a (missing-script-file mid-loop) and T-ENV-26 (embedded-NUL env-entry rejection at spawn); install failure (download, preflight, staging, commit) → exit 1 covered by T-INST-92 / T-INST-92a / T-INST-92b (HTTP error), T-INST-92c (transport / connection-reset error), T-INST-78 / T-INST-80a (preflight), T-INST-79 (staging, via seam), T-INST-80c (commit, via seam); `.gitignore` safeguard write failure (SPEC 10.10) → exit 1 covered by T-INST-112c (via seam) plus no-rollback assertion T-INST-112d; `npm install` non-zero exit and spawn failure → exit 1 covered by T-INST-114 / T-INST-114a / T-INST-114b / T-INST-114d (mixed safeguard / non-zero / spawn-failure aggregate); signal during `npm install` → exit `128+signal` covered by T-INST-116 / T-INST-116a / T-INST-116b2 (SIGTERM-axis remaining-workflows-not-processed parity) / T-INST-116d2 (SIGTERM-axis partial-`node_modules/`-not-cleaned parity) / T-INST-116f, and signal during the auto-install pass when no npm child is active → exit `128+signal` covered by T-INST-116h (`between-workflows-after-first` ordinal SIGINT) / T-INST-116h2 (SIGTERM parity) / T-INST-116i (`pre-spawn-first` ordinal SIGINT) / T-INST-116i2 (SIGTERM parity) / T-INST-116j (`post-exit-first` ordinal SIGTERM after a successful npm exit) / T-INST-116j2 (`post-exit-first` ordinal SIGINT after a non-zero npm exit) / T-INST-116j3 (`post-exit-first` ordinal SIGTERM after a non-zero npm exit) / T-INST-116k (`post-safeguard-failure-first` ordinal SIGINT) / T-INST-116k2 (SIGTERM parity) / T-INST-116l (`post-aggregate-report` already-emitted carve-out SIGINT) / T-INST-116l2 (SIGTERM parity); cleanup-warning-does-not-mask-error-path (SPEC 7.4 + 12) covered by T-TMP-35c (CLI) / T-TMP-35d (`runPromise`) / T-TMP-35e (`run` generator); usage errors enumerated in SPEC 12's final paragraph → exit 1 covered across the T-CLI-RUN-DASHDASH-01–07, T-CLI-RUN-DASHDASH-10, T-CLI-RUN-DASHDASH-11, T-CLI-RUN-DASHDASH-12, T-CLI-RUN-DASHDASH-13, T-CLI-RUN-NAMEVAL-01–03, T-CLI-RUN-NAMEVAL-06, T-CLI-RUN-NAMEVAL-07, T-CLI-27, T-CLI-86, T-CLI-96, install-parsing T-INST-* bands, T-SUB-06c / T-SUB-06d / T-SUB-06e (subcommand-argument usage errors — missing operands and unknown flags on `loopx output`), T-CLI-01a / T-CLI-01b (version-subcommand grammar — extra positional and unrecognized `--help` / `-h` are usage errors; encoded as the most-natural reading of SPEC 4.3 / 11 / 12 and outside the ADR-0004 surface), and T-INST-DASHDASH-01 / T-INST-DASHDASH-02 (install `--` rejection — exit 1) plus T-INST-DASHDASH-03 / T-INST-DASHDASH-04 (install `-h` / `--help` short-circuit suppresses `--` rejection — exit 0, included here as the SPEC 12 / 4.2 cross-cutting exit-0 counterpart to the rejection cases). |
+| 13 | Summary of Special Values | *(Summary-only section — LOOPX_BIN: T-MOD-19–21, T-MOD-21a, T-ENV-20, T-ENV-20a, T-ENV-20b, T-ENV-21e, T-DEL-05; LOOPX_PROJECT_ROOT: T-EXEC-03–03a, T-ENV-21, T-ENV-21a, T-ENV-21d, T-ENV-21f, T-SYM-02, T-SYM-03, T-SYM-04, T-SYM-04a, T-SYM-04b, T-PWD-06; LOOPX_WORKFLOW: T-EXEC-04–04c, T-ENV-21b, T-ENV-21c; LOOPX_WORKFLOW_DIR: T-WFDIR-01–14, T-ENV-21g, T-SYM-02c, T-SYM-04c, T-SYM-05; LOOPX_TMPDIR: T-TMP-01–11, T-TMP-02a, T-TMP-12, T-TMP-13, T-TMP-13a, T-TMP-13b, T-TMP-14, T-TMP-14a, T-TMP-15–23, T-TMP-18b, T-TMP-24, T-TMP-24c, T-TMP-24d, T-TMP-25–29, T-TMP-29f, T-TMP-29g, T-TMP-29h, T-TMP-30, T-TMP-31, T-TMP-35c, T-TMP-37a, T-TMP-37b, T-TMP-37c (rule-3 hard-link `nlink`-safety), T-ENV-21h, T-API-60, T-API-60a (T-TMP-12d/12e/38/39 are seam-backed direct conformance pins via `LOOPX_TEST_TMPDIR_FAULT` / `LOOPX_TEST_TERMINAL_TRIGGER_PAUSE`; remaining SPEC-7.4 known gaps are T-TMP-43, T-TMP-44, T-SIG-29, T-SIG-30b / T-API-10j — see SPEC-7.4 row above); LOOPX_DELEGATED: T-DEL-04, T-DEL-07, T-DEL-07a, T-DEL-09, T-DEL-09a, T-ENV-24a, T-ENV-24a2, T-ENV-24a3, T-ENV-24a4, T-ENV-24a5, T-ENV-24a6 (full four-tier ordinary precedence), T-API-58a, T-INST-115b; `PWD` (intentionally not reserved): T-PWD-01–04, T-PWD-06, T-PWD-07, T-PWD-08, T-EXEC-01, T-EXEC-02, T-EXEC-16b (T-PWD-05 is a non-normative reminder, not an executable test); `index` convention: T-DISC-17–20, T-CLI-108–110, T-CLI-109a, T-INST-64, T-INST-64b–64d, T-INST-74a, T-INST-75a, T-INST-76a, T-LOOP-31c, T-API-20j2, T-API-20p2, T-API-20p3, T-API-45a, T-VER-24d, T-VER-24e, T-VER-25b, T-VER-25c, T-SIG-28; `:` delimiter: T-CLI-112–118, T-CLI-120a, T-CLI-120b, T-LOOP-36–42, T-API-30–44, T-INST-63b, T-INST-63c, T-INST-63e, T-SIG-27)* |
diff --git a/adr/0004-script-execution-context.md b/adr/0004-script-execution-context.md
new file mode 100644
index 0000000..a738131
--- /dev/null
+++ b/adr/0004-script-execution-context.md
@@ -0,0 +1,280 @@
+# ADR-0004: Script Execution Context, CLI Grammar, and Workflow Auto-Install
+
+**Status:** Proposed
+
+---
+
+## Context
+
+Four pain points have emerged as workflows have grown.
+
+1. **Intermediate data between scripts in a run.** Workflows like `review-adr`, `apply-adr`, and `spec-test-adr` stash hand-off files (`.feedback.tmp`, `.claude-output.tmp`, `.answer.tmp`, `.prompt.tmp`) in their own workflow directory or in `.loopx/shared/`. Cleanup is `rm -f` on the happy path; leaked files accumulate on error/signal/unexpected termination and are indistinguishable from legitimate content. `ralph`'s hand-maintained `.iteration.tmp` counter has the same issue — intra-run state leaking into the workflow directory because there is no per-run scratch space.
+
+2. **Per-run parameterization from programmatic callers.** `run()` / `runPromise()` callers have no way to inject per-invocation env vars without mutating `process.env` globally, which is racy under concurrent calls. The CLI already handles this natively via shell env-var prefix (`adr=0003 loopx run review-adr`); the programmatic API has no equivalent.
+
+3. **`$LOOPX_PROJECT_ROOT` prefix boilerplate in every script.** SPEC §6.1 currently makes each script's cwd its workflow directory, so `.loopx/` scripts open with `ROOT="$LOOPX_PROJECT_ROOT"` and prefix every reference to reach project files. The §6.1 justification ("relative imports and `node_modules/` resolve naturally") is inaccurate — Node ESM, tsx, and Bun all resolve bare specifiers and relative imports from the importing file's directory, not cwd.
+
+4. **Manual `npm install` after `loopx install`.** Workflows declaring npm dependencies in a `package.json` require `node_modules/` to be populated before scripts can run. SPEC §2.1 and §10.9 currently place this on the user: `cd .loopx/<workflow>/ && npm install` after every install or `-y` replacement. Forgetting it surfaces as a runtime module-resolution error on first script invocation rather than a clear install-time failure — and the step is trivially automatable since loopx already runs on a Node-capable host.
+
+An earlier draft proposed a `loopx run … -- name=value` CLI surface. It is not adopted in v1: shell env-var prefixing is already sufficient for passing parameters, and the parser surface would add substantial complexity (two-phase parsing, name grammar, duplicate detection, `LOOPX_*` reservation, precedence tier reordering) without matching value. Scripts validate inputs themselves (`: "${adr:?need adr}"` in Bash; explicit checks in TS).
+
+A generic session-state mechanism (first-class iteration counter, key-value store) was deferred. Scripts that need such state maintain it in `$LOOPX_TMPDIR`.
+
+## Decision
+
+### 1. `LOOPX_TMPDIR` — run-scoped temporary directory
+
+For each `loopx run` (CLI) or `run()` / `runPromise()` (programmatic) invocation that reaches execution, loopx creates a unique temporary directory before the first child process spawns and injects its absolute path into every script's environment as `LOOPX_TMPDIR`.
+
+**Location, naming, and mode.** The directory is created under Node's `os.tmpdir()` via `mkdtemp` with a `loopx-` prefix, mode `0700`. The exact name format beyond the prefix is implementation-defined. The tmpdir parent (the `TMPDIR` / `TEMP` / `TMP` values that `os.tmpdir()` reads) is captured on the same schedule as the inherited `process.env` snapshot: synchronously at the `runPromise()` call site for `runPromise()`, and at first `next()` alongside the rest of the pre-iteration sequence for `run()` and the CLI. `TMPDIR` / `TEMP` / `TMP` entries in env files or `RunOptions.env` reach spawned scripts but do not mutate loopx's own `process.env` and therefore do not redirect the tmpdir parent. Because the tmpdir parent is captured on the same schedule as inherited env, a synchronous `process.env.TMPDIR = …` mutation after `runPromise()` returns does not affect the tmpdir parent; callers who need a specific parent for `runPromise()` set `TMPDIR` in loopx's inherited environment before the call. For `run()`, mutations to `process.env.TMPDIR` after `run()` returns but before the first `next()` **are** observed, for the same reason that inherited-env mutations in that window are observed.
+
+**Scope and lifecycle.**
+
+- **Created:** once per run, after the pre-iteration sequence (discovery, env-file loading, target resolution, version check) and immediately before the first child spawns. Pre-spawn failures, `-n 0` / `maxIterations: 0` early exits, and aborts observed before tmpdir creation do not create a tmpdir.
+- **Shared across iterations.** All scripts — starting target, intra- and cross-workflow `goto` destinations, loop resets — observe the same `LOOPX_TMPDIR` value.
+- **Persisted within the run.** Files written by one script remain visible to later scripts.
+- **Concurrent runs are isolated.** Each run receives its own distinct directory.
+
+**Cleanup.** loopx runs cleanup on every terminal outcome of a run that reached tmpdir creation:
+
+- Normal completion (`stop: true` from a script, or `-n` / `maxIterations` reached).
+- Non-zero script exit; invalid `goto` target; missing workflow or script during `goto` resolution.
+- Child launch / spawn failure after tmpdir creation (discovered script removed or renamed per §5.1; runtime rejection of a child env entry from any env tier, most reliably an entry whose name or value contains an embedded NUL byte; `exec` failure; any other pre-first-line-of-user-code spawn-path error).
+- SIGINT / SIGTERM to loopx — after any active child process group exits (per §7.3, including SIGKILL escalation), before loopx exits with the signal's code. If no child is active, cleanup runs immediately.
+- Programmatic `AbortSignal` abort — after any active child process group exits per §9.1, before the generator throws or the promise rejects.
+- Consumer-driven cancellation under `run()` (`break` from `for await`, `.return()` / `.throw()` after first `next()`) — after terminating any active child per §9.1, before the generator settles.
+
+For `run()`, cleanup on normal completion is guaranteed only once the generator is driven to settlement (`{ done: true }`, `.return()`, `.throw()`, or a `for await` loop that runs to completion). The final yielded `Output` is not itself settlement; a caller that consumes the final output and abandons the generator may leak the tmpdir.
+
+Cleanup does **not** run when loopx itself is killed via SIGKILL or the host crashes; leaked tmpdirs are expected to be reaped by OS temp-cleaning policy. loopx does not reap stale tmpdirs at startup.
+
+**Cleanup idempotence.** loopx performs at most one cleanup attempt per created `LOOPX_TMPDIR` over the lifetime of the run. Racing terminal triggers (SIGTERM during cleanup of a prior SIGINT; abort concurrent with consumer `.return()` / `.throw()`; non-zero exit concurrent with abort; abort after final yield concurrent with a consumer `.throw()`; child spawn failure concurrent with abort; abort concurrent with tmpdir creation failure; etc.) do not start a second cleanup attempt.
+
+**Terminal-outcome precedence.** The selection of which terminal outcome is surfaced is governed by explicit precedence rules elsewhere in this ADR where they apply — the pre-first-`next()` consumer-cancellation carve-out, the abort-wins-over-pre-iteration-failures rule, the CLI pre-iteration signal-wins rule, and the abort-after-final-yield rule. Except where an explicit precedence rule applies, the first terminal trigger observed by loopx determines the surfaced outcome among genuinely racing triggers. "Observed by loopx" refers to the point at which the trigger enters loopx's own tracking (signal handler, abort listener, child-exit callback, consumer interaction) — not OS-level delivery order. Idempotence and warning cardinality are independent of which outcome surfaces.
+
+**Cleanup safety.** Cleanup is path-based and best-effort — not a sandbox against actively racing same-user processes. loopx captures an identity fingerprint (e.g., device/inode pair) of the created directory at creation time, before any child is exposed to the directory. At cleanup time, loopx `lstat`s the `LOOPX_TMPDIR` path and dispatches on the outcome:
+
+1. **Path no longer exists (ENOENT):** no-op.
+2. **Path is a symlink:** unlink the symlink entry; do not follow the target.
+3. **Path is a regular file, FIFO, socket, or other non-directory non-symlink:** leave in place with a stderr warning. Unlinking would risk mutating unrelated data (hard-link `nlink` decrement, or data renamed into the path with `nlink == 1`).
+4. **Path is a directory whose identity matches the recorded identity:** recursively remove. Symlink entries encountered during the walk are unlinked but not traversed, so symlinks pointing outside the tmpdir do not collateral-delete their targets.
+5. **Path is a directory whose identity does not match:** leave in place with a stderr warning. loopx does not recursively remove a directory it did not create.
+
+If the top-level `lstat` fails for any reason other than ENOENT, the `unlink` in case 2 fails, or the recursive removal in case 4 fails, loopx emits a single stderr warning and makes no further changes. Per-cleanup-attempt warning cardinality is at most one; combined with cleanup idempotence this bounds every run to at most one cleanup warning. The warning text format — including whether to identify a category, how to render the affected path, and how to describe the underlying errno — is implementation-defined. Warnings do not affect the CLI exit code, the generator outcome, or the promise rejection reason.
+
+A script that removes or renames its tmpdir during the run defeats automatic cleanup of the moved directory; loopx does not chase renamed tmpdirs. loopx does not detect or avoid mount points inside `$LOOPX_TMPDIR`; scripts that mount into `$LOOPX_TMPDIR` take responsibility for unmounting before cleanup. A race-resistant guarantee against a same-user process actively mutating the path during cleanup (fd-relative `openat` / `unlinkat` with `AT_SYMLINK_NOFOLLOW`) is out of scope for v1.
+
+**Creation order.** loopx creates the directory with `mkdtemp`, captures its identity fingerprint, then verifies or secures mode `0700` — in that order. The path is not exposed to any child process before all three steps complete successfully. This order is normative because it determines what cleanup-safety guarantee applies if a creation step fails.
+
+**Creation failure.** If any step fails, loopx does not spawn any child; the CLI exits `1`, `run()` throws on first iteration, `runPromise()` rejects. The cleanup performed before surfacing the creation error depends on which step failed:
+
+- **`mkdtemp` itself fails:** no path exists, so no cleanup is needed.
+- **Identity capture fails (after `mkdtemp` succeeded):** loopx attempts a single non-recursive `rmdir` on the path. This succeeds on an empty directory (the expected state immediately after `mkdtemp`) and fails without side effects on a symlink, non-directory, or non-empty directory. Without a recorded identity fingerprint, this remains outside the race-resistant guarantee: a same-user process that swapped the original `mkdtemp` directory for a different empty directory before the `rmdir` would have that replacement removed. loopx accepts this narrow trade-off as the cost of cleaning up the common identity-capture-failure case. If `rmdir` fails, loopx emits a single stderr warning and leaves the path in place.
+- **Mode-securing fails (after `mkdtemp` and identity capture succeeded):** loopx runs the full cleanup-safety routine above, with the recorded identity fingerprint in hand.
+
+Cleanup failure during creation-failure handling emits at most one warning but does not mask the original creation error. If a SIGINT/SIGTERM or `AbortSignal` abort arrives concurrently with a creation failure, the signal/abort wins and any partial directory is cleaned up under the same rules.
+
+**Programmatic settlement and pre-iteration precedence.** The rules below refine SPEC §9.1's existing "abort always produces an error, even if it occurs before the first `next()` call" through the full pre-iteration sequence.
+
+- **Pre-first-`next()` consumer cancellation on `run()` wins over all pre-iteration state.** A `.return(value)` or `.throw(err)` call as the consumer's *first* interaction with a generator returned by `run()` settles the generator per standard JS async-generator semantics; the loop body is never entered. No pre-iteration step runs and no pre-iteration error is surfaced: captured call-time option-snapshot errors (invalid `options` values, invalid `options.signal`, non-string `options.cwd` / `options.envFile`, invalid `options.maxIterations`, invalid `options.env` shape, throwing option-field getters, throwing `options.env` enumerable getters or proxy traps), invalid `target` values and target-syntax validation, `.loopx/` discovery failures, env-file loading failures, target resolution failures, and tmpdir creation failures are all suppressed. A `signal` captured at call time is not consulted; even an already-aborted signal does not surface the abort error through this path. This applies only to `run()`; `runPromise()` has no equivalent carve-out. Once the consumer's first interaction is `next()`, the body is entered and captured state is observed.
+- **Once a usable `AbortSignal` has been captured, abort wins over all other pre-iteration failures on the same call.** A signal that was already aborted at call time, or that aborts during pre-iteration before the first child spawn, displaces all other pre-iteration failure modes (captured option-snapshot errors, target argument / target syntax validation, `.loopx/` discovery, env-file loading, target resolution, tmpdir creation). An invalid `options` value or non-`AbortSignal`-compatible `options.signal` captures no signal and does not enter this pathway — they are ordinary option-snapshot errors. Version checking is not a failure mode per SPEC §3.2, so it does not compete.
+- **`options.signal` is read before other `RunOptions` fields.** This guarantees an already-aborted signal is captured before any other option-field read can produce a snapshot exception. The order of the remaining option fields (`options.env`, `options.cwd`, `options.envFile`, `options.maxIterations`) is implementation-defined. Each option field is read at most once per call, and a throwing getter or proxy trap is not re-invoked to retry.
+- **Project-root-blocking and envFile-path-blocking option errors surface before the four project-root-dependent failures.** A non-string `options.cwd`, throwing `options.cwd` getter, non-string `options.envFile`, or throwing `options.envFile` getter must surface before `.loopx/` discovery errors, env-file loading errors, target resolution errors, or tmpdir-creation errors — otherwise an unrelated non-options error detected under a garbage project root would obscure the actual cause. The pinning is scoped to that set only; relative priority between these pinned option errors and target argument / target syntax validation is implementation-defined. Relative priority among the remaining non-abort pre-iteration errors (invalid `options`, invalid `options.signal`, invalid `options.maxIterations`, invalid `options.env` shape and snapshot-time throws, target argument / target syntax validation, and the four project-root-dependent failures) is implementation-defined.
+- **CLI signal precedence during pre-iteration.** SIGINT / SIGTERM *observed by loopx's installed pre-iteration signal handler* wins over non-signal pre-iteration failures not yet surfaced at that point: loopx cleans up any partial tmpdir and exits with `128 + signal number` regardless of which non-signal pre-iteration step (target syntax validation, `.loopx/` discovery, env-file loading, target resolution, tmpdir creation) would otherwise have failed. The contract is phrased around handler observation, not OS-level delivery — implementations are not required to make pre-iteration async or poll for pending signals between steps. Signal-wins precedence begins only after the `run -h` / `--help` short-circuit and usage-level argument parsing have completed *and* loopx has installed its pre-iteration signal handlers. Signals delivered in the pre-handler-installation window (process startup, argument parsing, help short-circuit) are outside this precedence: either the runtime applies POSIX default signal disposition and terminates the process, or parsing completes and the parser-level usage error surfaces. Both outcomes are conforming.
+- **Abort after the final yielded `Output` still wins until generator settlement.** An `AbortSignal` that aborts after the final `Output` has been yielded (via `stop: true` or `maxIterations` reached) but before the generator settles via `{ done: true }` produces the abort error on the next generator interaction — `g.next()`, `.return()`, or `.throw()`. Normal completion is fixed only at settlement, not at the final yield. Cleanup runs before the abort error is surfaced.
+- **The CLI retains SPEC §7.1's concrete pre-iteration ordering.** The programmatic-API precedence rules above are scoped to `run()` / `runPromise()`. CLI tests may assert §7.1's documented order.
+
+### 2. `RunOptions.env`
+
+`RunOptions` gains an optional `env` field:
+
+```typescript
+interface RunOptions {
+  maxIterations?: number;
+  envFile?: string;
+  signal?: AbortSignal;
+  cwd?: string;
+  env?: Record<string, string>;
+}
+```
+
+- **Shape.** `env` must be omitted, `undefined`, or a non-null, non-array, non-function object whose own enumerable string-keyed entries all have string values. Symbol-keyed, non-enumerable, and inherited properties are ignored. Invalid shapes (null, array, non-object, function, or an entry with a non-string value) are captured at call time and surfaced via the standard pre-iteration error path.
+- **Lifetime.** Entries are captured synchronously at call time as a shallow copy — loopx reads the supplied object's own enumerable string-keyed properties once. The capture runs at the `run()` / `runPromise()` call site but never throws at the call site; any exception raised during the snapshot (a `Proxy` `ownKeys` trap that throws, a throwing enumerable getter, a throwing `options.env` getter on the options object) is captured and surfaced through the standard pre-iteration error path. Mutating the original object after `run()` / `runPromise()` returns has no effect on the running loop.
+- **Merge position.** `env` entries merge into the child environment *after* global and local env-file loading and *before* loopx-injected protocol variables (`LOOPX_BIN`, `LOOPX_PROJECT_ROOT`, `LOOPX_WORKFLOW`, `LOOPX_WORKFLOW_DIR`, `LOOPX_TMPDIR`). A `RunOptions.env` entry overrides same-named values from `-e`, the global loopx env file, and inherited `process.env`, and is overridden by protocol variables.
+- **Applies to every script in the run.** Starting target, intra- and cross-workflow `goto` destinations, and loop resets all receive the same `env` additions.
+- **No CLI surface.** Programmatic-only. CLI callers pass per-run values via the shell env prefix (`key=value loopx run …`), which flows through inherited `process.env`, or via `-e` / `loopx env set` for file-based config.
+- **No name validation beyond string-to-string.** loopx does not enforce the POSIX `[A-Za-z_][A-Za-z0-9_]*` name pattern, does not reject `LOOPX_*` keys (they are silently overridden by protocol injection), does not reject `=` or empty-string names, and does not reject NUL bytes. Runtime-level rejections — most reliably a name or value containing an embedded NUL byte — surface as child launch / spawn failures at spawn time (any env tier may be the source; the runtime does not distinguish tiers). `RunOptions.env` shape validation (invalid object types, non-string values, snapshot-time throws) is independent of spawning and surfaces on the programmatic API under `maxIterations: 0` just as under any other iteration count. The CLI has no `RunOptions.env` to validate, so this shape-validation path does not apply to `-n 0`; `-n 0` does still validate env files.
+- **`LOOPX_DELEGATED` is not a script-protocol-protected variable.** SPEC §3.2 sets `LOOPX_DELEGATED` only on the inner loopx process during project-root delegation, not on every script spawn. This ADR does not add `LOOPX_DELEGATED` to the per-spawn protected tier; env files, inherited `process.env`, and `RunOptions.env` may supply it to spawned scripts. The SPEC §3.2 startup behavior is unchanged.
+
+**Invalid option values.** `options` must be omitted, `undefined`, or a non-null, non-array, non-function object. `options.signal`, when present and not `undefined`, must be an `AbortSignal`-compatible object exposing a readable `aborted` and an `addEventListener('abort', listener)` method that is callable and returns without throwing when loopx invokes it to register its abort listener. `options.cwd` and `options.envFile`, when present and not `undefined`, must be strings. `options.maxIterations` retains its existing SPEC §9.5 validation. Non-conforming values — including throwing getters on the options object — are captured at call time and surfaced via the standard pre-iteration error path rather than escaping at the call site. `removeEventListener` is not part of the `AbortSignal`-compatibility contract: loopx does not require its presence, and whether loopx invokes it on settlement is implementation-defined.
+
+**Duck-typed signal reentrancy.** For non-`AbortSignal` duck-typed signals: if `addEventListener` synchronously invokes the registered listener during registration, or if `aborted` is observed as `true` at any point during call-time capture, loopx treats the signal as aborted. Real `AbortSignal` instances passed in an already-aborted state must be observed as aborted regardless of implementation latitude. Other reentrant behavior — `aborted` transitioning between reads within the same call, ordering between reading `aborted` and registering the listener for duck-typed signals — is implementation-defined.
+
+**Inherited `process.env` snapshot.** loopx snapshots the caller's `process.env` once per run; mutations between spawns do not propagate. For `run()`, the snapshot is lazy — captured on the first `next()` call alongside the rest of the pre-iteration sequence, so mutations between `run()` returning and first `next()` **are** observed. For `runPromise()`, the snapshot is captured synchronously at the `runPromise()` call site, before `runPromise()` returns; synchronous mutations after return are not observed. Callers who need a deterministic per-run value under either API should use `RunOptions.env`, which sits above inherited env in §8.3 and is captured at call time.
+
+Global env file path resolution (`$XDG_CONFIG_HOME/loopx/env`, with the documented `HOME`-based fallback) reads `XDG_CONFIG_HOME` / `HOME` from the inherited environment on the same schedule as the inherited-env snapshot (lazy for `run()`, at call time for `runPromise()`). `RunOptions.env` does not affect global-env-file path resolution because `env` merges after env-file loading.
+
+### 3. Project-root cwd
+
+Every child process loopx spawns for script execution uses `LOOPX_PROJECT_ROOT` as its working directory. This replaces SPEC §6.1's current rule that scripts run with the workflow directory as cwd.
+
+- **CLI.** The CLI's invocation cwd is the project root (SPEC §3.2). The spawned script cwd becomes the same path — unchanged from the CLI user's terminal perspective but different from the child script's perspective.
+- **Programmatic.** `RunOptions.cwd` (or `process.cwd()` at call time when omitted) specifies both the project root and the script execution cwd. A relative `RunOptions.cwd` is resolved via `path.resolve(process.cwd(), options.cwd)` once at call time; an absolute value is used unchanged. No `realpath` / canonicalization is applied. SPEC §9.5's current "cwd does not control script execution cwd" disclaimer is dropped.
+- **Applies to every script in the run.** Starting target, intra- and cross-workflow `goto` destinations, and loop resets all receive the same cwd.
+- **Scripts remain free to change directory.** `cd` / `process.chdir()` changes are scoped to that child process; later spawns always start at project-root cwd.
+- **Script module resolution is unaffected by cwd.** Node ESM, tsx, and Bun resolve bare specifiers and relative imports from the importing module's file path, not cwd. SPEC §3.3's current claim that closer-`node_modules` precedence is "a natural consequence of running scripts with the workflow directory as cwd" is incorrect and retired by this ADR. The custom Node/tsx resolve hook (SPEC §3.3) must preserve standard precedence: it must first attempt standard file-relative resolution (via `defaultResolve` delegation or an equivalent file-path walk-up) and fall back to the CLI package exports only when no `node_modules/loopx` is found by standard resolution. Note that Node's default main-module handling applies `realpath` to the main module's file path; when the absolute discovery-time entry path traverses any symlink (workflow directory entry, entry script file, or intermediate ancestor), the resolver walks up from the canonical target rather than the symlink-preserving spelling, and workflow-local `node_modules/loopx` on the logical path is not guaranteed to win even with a correctly delegating hook.
+- **No canonicalization.** loopx does not apply `realpath` beyond what the runtime already provides. For the CLI, `LOOPX_PROJECT_ROOT` is exactly the string returned by loopx's own `process.cwd()` at invocation; loopx does not consult `$PWD`. On POSIX systems where `getcwd(3)` canonicalizes, a CLI invocation from a symlinked directory yields a canonical `LOOPX_PROJECT_ROOT`. For the programmatic API, `LOOPX_PROJECT_ROOT` is `RunOptions.cwd` (with `path.resolve` applied only if relative) or `process.cwd()` at call time. `path.resolve` is a pure string operation; symlinked components supplied in `RunOptions.cwd` are preserved verbatim. Callers who need a canonical realpath compute one themselves.
+- **Directory identity vs. string spelling.** loopx controls the child's *effective working directory* by spawning with `LOOPX_PROJECT_ROOT` as cwd (same device/inode as `LOOPX_PROJECT_ROOT`) but does not control the *string spelling* that runtime cwd APIs report. Under a symlinked project root, Node/Bun's `process.cwd()` typically canonicalizes via `getcwd(3)` while `LOOPX_PROJECT_ROOT` preserves the symlinked spelling; both name the same directory. Bash `$PWD` and bare `pwd` are shell-maintained and inherit loopx's own `PWD`, so byte-for-byte equality between Bash `$PWD` / bare `pwd` and `LOOPX_PROJECT_ROOT` is not a loopx guarantee in any regime. Scripts that need the loopx-chosen spelling read `LOOPX_PROJECT_ROOT`; scripts that need the kernel cwd spelling use `process.cwd()` (JS/TS) or `pwd -P` / `/bin/pwd` (Bash); scripts that need filesystem identity use `stat(".")`.
+- **`PWD` is not a protocol variable.** loopx neither sets nor unsets `PWD` in the child environment; whatever value loopx's own process holds is inherited unchanged. A caller who wants a specific `PWD` in the child passes it via `RunOptions.env` or inherited env, subject to Bash's standard POSIX inheritance behavior. `PWD` is outside the §8.3 protocol-variable tier and outside the §13 reserved list.
+- **Breaking change vs. current SPEC §6.1.** Scripts using `./foo` or `readFileSync("./foo")` to reach workflow-local files break. Migration: `"$LOOPX_WORKFLOW_DIR/foo"` (Bash) or `resolve(process.env.LOOPX_WORKFLOW_DIR, "foo")` (JS/TS). Existing workflow scripts in this repo must be audited and migrated as part of implementing this ADR; notably `.loopx/shared/dispatch.sh` uses cwd-relative references (`./send-telegram.sh`, `./send-codex.sh`, `./node_modules/.bin/tsx ./send-api.ts`, `./node_modules/.bin/tsx ./send-batch.ts`) that require migration, and the `.loopx/shared/` helpers' use of workflow-local `node_modules/` via `./node_modules/.bin/tsx` needs to be replaced with a `$LOOPX_WORKFLOW_DIR`-rooted path.
+
+### 4. `LOOPX_WORKFLOW_DIR` injection
+
+loopx injects `LOOPX_WORKFLOW_DIR` into every script's environment, set to the absolute path of the workflow directory containing the currently-spawned script.
+
+- **Value.** The directory portion of the cached absolute discovery-time script path for the currently-spawned script — the same path by which loopx spawns the script (see "Scripts are invoked by absolute discovery-time path" below). In the v1 layout this normally corresponds to `"$LOOPX_PROJECT_ROOT/.loopx/$LOOPX_WORKFLOW"`, but the injected form is derived from the cached discovery path rather than recomposed from those components, so it remains consistent with the spawn path under trailing-slash variations, symlinked `.loopx/<workflow>` entries, and any lexical normalization the implementation applies during discovery. The injected form is authoritative; scripts should prefer it over re-deriving the path.
+- **Per-spawn refresh — cross-workflow `goto` semantics.** `LOOPX_WORKFLOW_DIR` tracks the currently-spawned script's containing workflow, refreshed alongside `LOOPX_WORKFLOW` across starting-target spawn, intra-workflow `goto`, cross-workflow `goto`, and loop reset. A cross-workflow `goto` A → B sets `LOOPX_WORKFLOW_DIR` to B's directory before the B-side spawn. Deeper chains (A → B → C) each observe their own workflow's directory.
+- **Stable within a single script execution.** A top-level workflow script and a sibling helper it sources or imports both read the same `LOOPX_WORKFLOW_DIR` — the env var is injected once per child spawn and inherited by the whole process.
+- **Scripts are invoked by absolute discovery-time path.** loopx spawns each script using the absolute path by which it was discovered under `.loopx/` (e.g., `bash /project/.loopx/review-adr/index.sh`). For Bash, `$0` is an absolute path; because Bash does not canonicalize `$0`, `$(dirname "$0")` equals `LOOPX_WORKFLOW_DIR` byte-for-byte regardless of whether symlinks appear anywhere in the entry path (workflow directory entry, entry script file, or intermediate component). This Bash equality is normative. For JS/TS, `dirname(fileURLToPath(import.meta.url))` equals `LOOPX_WORKFLOW_DIR` only when the absolute entry path is symlink-free in every component; Node applies `realpath` to the main module's file path by default, and Bun's behavior is not specified to match. `LOOPX_WORKFLOW_DIR` is authoritative for JS/TS code that needs the discovery-time workflow path.
+- **Symlink behavior.** `LOOPX_WORKFLOW_DIR` is derived from the project root plus the `.loopx/<workflow>` entry name as discovered, not via `realpath`. A symlinked `.loopx/<workflow>` directory entry, a symlinked `.loopx` directory, a symlinked entry script file, or a symlinked project-root ancestor (via `RunOptions.cwd`) all preserve their discovered spelling in `LOOPX_WORKFLOW_DIR`.
+- **Protocol-variable tier.** `LOOPX_WORKFLOW_DIR` joins `LOOPX_BIN`, `LOOPX_PROJECT_ROOT`, `LOOPX_WORKFLOW`, and `LOOPX_TMPDIR` in the top precedence tier of SPEC §8.3. User-supplied values in any lower tier are silently overridden.
+- **Not a cross-workflow rendezvous.** Scripts handing data across a cross-workflow `goto` use `$LOOPX_TMPDIR` (preferred) or a shared fixed location like `$LOOPX_PROJECT_ROOT/.loopx/shared/…`.
+
+### 5. CLI grammar — v1 scope
+
+Outside the existing `run -h` / `--help` short-circuit (SPEC §4.2), `loopx run` does not accept a named-argument, key-equals-value, or per-run-parameter CLI syntax. A `name=value` token in the positional tail is not interpreted as a named argument: a second positional after the target is rejected as "more than one positional" (SPEC §4.1), and a sole positional `name=value` is parsed as a target string that fails target validation because `=` is not in the `[a-zA-Z0-9_][a-zA-Z0-9_-]*` pattern.
+
+v1 also does not accept `--` as an end-of-options marker in `run`'s argument list (outside `-h` / `--help`): wherever it appears, it is rejected as an unrecognized flag / usage error under the existing §4.1 / §4.2 rejection rules. This follows from the v1 decision not to adopt a named-argument tail — the rejection is parser simplification, not a permanent product stance. A later ADR that adopts a first-class CLI named-argument surface may revisit both the tail and `--` support.
+
+The `run -h` / `--help` short-circuit is preserved exactly as in SPEC §4.2: when `-h` / `--help` appears anywhere in the `run` argument list, loopx shows run help, exits `0`, and ignores all other run-level arguments unconditionally (including `--` in any position, extra positionals, duplicate or invalid `-n` / `-e`, unrecognized flags, and any `name=value` tokens). The sole CLI surface for per-run values is the shell env prefix (`key=value loopx run <target>`), which flows through inherited `process.env` at the §8.3 inherited-env tier. Callers who want file-backed precedence above inherited env use `-e <path>` or `loopx env set`.
+
+### 6. Auto-install workflow dependencies during `loopx install`
+
+This decision is not a script-execution-context concern in the strict sense — it surfaced during analysis of how to optimize the usage of existing workflow flows, where the manual post-install `npm install` step repeatedly came up as avoidable friction. It is bundled into this ADR rather than spun off into its own because the fix is small and the motivation (having dependencies resolvable when scripts first import them) is adjacent to the other four decisions.
+
+After `loopx install` commits workflow files (§10.7), loopx spawns `npm install` in each committed workflow that contains a top-level `package.json`. This replaces SPEC §2.1 / §10.9's manual-install requirement. The existing §10.9 statement "loopx does not run `npm install` or `bun install` after cloning/extracting" is retired by this ADR.
+
+- **Trigger.** Runs once per committed workflow with a top-level `package.json` file (`.loopx/<workflow-name>/package.json`), sequentially in commit order, with cwd set to the workflow directory. Workflows without a top-level `package.json` are skipped silently — no warning, no npm invocation. When `-w <name>` restricts the install to a single workflow, auto-install considers only that workflow.
+
+- **Package manager.** `npm install` unconditionally. loopx does not inspect `bun.lockb`, `pnpm-lock.yaml`, `yarn.lock`, or a `packageManager` field to select a different manager, and does not pass `--production` / `--omit=dev` / `--ignore-scripts` / any other flags — whatever the workflow's `package.json` and the user's npm configuration prescribe is what runs. Workflow authors needing a different manager pass `--no-install` and invoke their preferred tool manually.
+
+- **Environment.** The `npm install` child inherits loopx's own `process.env` unchanged. `LOOPX_*` protocol variables, `RunOptions.env`, and env-file entries are not injected — these are script-execution-context concerns, not install-time concerns.
+
+- **Output.** npm's stdout and stderr stream through to loopx's stdout and stderr unchanged; loopx neither buffers nor parses npm output and does not introduce a progress indicator of its own.
+
+- **`--no-install` opt-out.** A new install-scoped boolean flag suppresses auto-install for every selected workflow in the current command. Duplicate `--no-install` is a usage error under the existing §4.2 duplicate-flag rule. The `install -h` / `--help` short-circuit continues to ignore `--no-install` unconditionally. `--no-install` does not suppress any other install-time behavior (source download, preflight validation, stage-then-commit); only the `npm install` step is skipped.
+
+- **Failure.** If `npm install` exits non-zero, or fails to spawn (most commonly: `npm` is not on `PATH`), loopx records the failure, proceeds with the next workflow's `npm install`, and exits `1` at the end if any workflow's npm install failed. Dependency-install failures do not roll back the file-level install: committed workflows remain on disk in the same partial-install sense as §10.7's commit-failure clause. Retries: `loopx install -y <source>` reinstalls from scratch, or `cd .loopx/<workflow> && npm install` retries manually.
+
+- **Malformed `package.json`.** When the workflow's `package.json` is unreadable, contains invalid JSON, or has an invalid `loopx` semver range (the §3.2 failure modes), the existing §3.2 warning is emitted and auto-install skips that workflow silently — loopx does not invoke `npm install` against a file that failed version validation and does not add a second warning for the same underlying failure.
+
+- **Interaction with `-y`.** File-level replacement removes the existing workflow directory (including any previously installed `node_modules/`) before the replacement is committed; `npm install` then runs fresh against the replacement's `package.json`.
+
+- **`.gitignore` safeguard for `node_modules/`.** Immediately before spawning `npm install` in a workflow directory, loopx checks for a top-level `.gitignore` in that workflow directory. If none exists, loopx creates one containing the single line `node_modules`. If a `.gitignore` already exists, loopx leaves it unchanged — the workflow author is responsible for the contents of a pre-existing `.gitignore`, and loopx does not append, rewrite, or warn about a missing `node_modules` entry. Runs under the same trigger conditions as `npm install`: once per committed workflow with a top-level `package.json`, skipped for workflows without one, skipped under the §3.2 malformed-`package.json` skip, and skipped under `--no-install`. A failure to create `.gitignore` (e.g., a read-only workflow directory) **skips `npm install` for that workflow** — loopx does not run `npm install` when the safeguard could not be established, since populating `node_modules/` without a covering `.gitignore` is exactly the hazard the safeguard is designed to prevent. The `.gitignore` failure is recorded on the same aggregate-report footing as an `npm install` spawn failure, loopx proceeds to the next workflow, and the failure contributes to the final exit `1`. Committed workflow files are not rolled back; the user can remediate by creating a `.gitignore` manually and running `cd .loopx/<workflow> && npm install`, or by re-running `loopx install -y <source>`.
+
+- **Signals during `npm install`.** SIGINT / SIGTERM received while an `npm install` child is active propagates to the child's process group. loopx waits for the child to exit (the §7.3 grace period and SIGKILL escalation rules apply by analogy) and then exits with the signal's code. Remaining committed workflows are not processed. Partial `node_modules/` state produced before interruption is not cleaned up by loopx.
+
+- **Trust profile.** Because `npm install` may execute arbitrary code via `preinstall` / `install` / `postinstall` scripts declared in the workflow's dependency graph, `loopx install` inherits the same trust profile as a manual `npm install` in the same directory. Users installing from untrusted sources should pass `--no-install` and inspect the workflow before running `npm install` themselves.
+
+## Consequences
+
+- **Workflow directories stop accumulating temp files.** Existing workflows migrate `.feedback.tmp` / `.claude-output.tmp` / `.answer.tmp` / `.prompt.tmp` / `ralph`'s `.iteration.tmp` into `$LOOPX_TMPDIR/…` and drop manual `rm -f` branches.
+- **Cleanup is automatic on failure.** Loops that error out, are signaled, or are aborted no longer leak scratch files. Callers who relied on lingering `.tmp` files for post-mortem inspection must write those outside `$LOOPX_TMPDIR` (e.g., under `$LOOPX_PROJECT_ROOT`).
+- **Cross-run state is the caller's responsibility.** `LOOPX_TMPDIR` never persists across runs. Workflows needing cross-run state use project-root-relative storage. `ralph`'s `.iteration.tmp` is intra-run state and migrates to `$LOOPX_TMPDIR/iteration`.
+- **Concurrent runs are safe.** Parallel `loopx run` invocations do not clobber each other's scratch files.
+- **Scripts drop `$LOOPX_PROJECT_ROOT`-prefix boilerplate.** `ROOT="$LOOPX_PROJECT_ROOT"; cat "$ROOT/SPEC.md"` becomes `cat SPEC.md`. `$LOOPX_PROJECT_ROOT` remains injected for scripts that `cd` elsewhere or hand paths to tools that don't inherit cwd.
+- **Tools invoked from scripts get project-root context by default.** `git`, `claude`, `codex`, and similar tools operate against the whole repo without scripts having to `cd` first. Scripts that want workflow-scoped tool behavior `cd "$LOOPX_WORKFLOW_DIR"` explicitly.
+- **`RunOptions.cwd` semantics simplify.** Previously `cwd` set only the project root; now it sets both the project root and the script execution cwd.
+- **Workflow-local cwd-relative references break.** Scripts using `./foo` now resolve against the project root. Migration: `"$LOOPX_WORKFLOW_DIR/foo"` (Bash) or `resolve(process.env.LOOPX_WORKFLOW_DIR, "foo")` (JS/TS). In this repo, `.loopx/shared/dispatch.sh` uses cwd-relative references and must be migrated as part of implementing this ADR.
+- **Workflow-local assets reachable in one token.** `cat "$LOOPX_WORKFLOW_DIR/prompt.md"` replaces `$(dirname "$0")` / `import.meta.url` tricks.
+- **Programmatic callers get per-run env without mutating `process.env`.** `RunOptions.env` is a clean shallow copy scoped to the call.
+- **CLI parameterization uses existing shell idioms.** `adr=0003 loopx run review-adr` continues to work at the inherited-env tier — overridden by both env files and `RunOptions.env`. loopx does not introduce a dedicated CLI override tier above `-e`.
+- **`RunOptions.env` fills a different gap than `-e`.** It lets programmatic callers pass per-run values without mutating `process.env`, without writing an on-disk file, and layered dynamically above `RunOptions.envFile`.
+- **Migration is manual but straightforward.** Existing workflows (1) replace in-workflow `.tmp` paths with `$LOOPX_TMPDIR/…` and drop `rm -f` cleanup, (2) take per-run parameters via shell env prefix, (3) optionally drop the `ROOT=…` header and `$ROOT/` prefixes. No automated migration tooling is provided.
+- **`loopx install` is a single command instead of two.** Workflows with a `package.json` are runnable immediately after `loopx install` without a follow-up `cd .loopx/<name> && npm install`. Existing documentation and README examples that instruct users to install dependencies manually are now redundant for the npm case.
+- **`npm install` must be available on the host.** If `npm` is not on `PATH` (e.g., a Bun-only environment), `loopx install` reports a spawn failure and exits `1` unless `--no-install` is passed. Hosts that cannot provide npm pass `--no-install` and run their preferred package manager manually.
+- **Install time increases.** `loopx install` now waits for `npm install` to finish, so wall-clock install time depends on dependency graph size. The `--no-install` escape hatch preserves the fast file-only install for CI scenarios that cache `node_modules/` separately.
+- **Package install hooks run by default.** Arbitrary `preinstall` / `install` / `postinstall` hooks in the workflow's dependency graph execute during `loopx install` under the same trust model as a manual `npm install` in the same directory. Users installing from untrusted sources should inspect first and pass `--no-install`.
+
+## Rejected / Deferred Alternatives
+
+- **First-class CLI named-argument syntax (e.g., `loopx run <target> -- name=value`).** Deferred. Shell env-var prefixing serves the v1 use cases; a dedicated parser would add substantial complexity without matching value.
+- **POSIX `--` end-of-options marker on `run` outside help.** Not supported in v1 as a consequence of the "no named-argument tail" decision. A later ADR may revisit alongside a named-argument surface.
+- **Named-argument schema.** Deferred. Scripts validate their own inputs.
+- **First-class iteration counter.** Deferred. Scripts maintain one in `$LOOPX_TMPDIR/iteration`.
+- **Stronger race-resistant tmpdir cleanup (`openat` / `unlinkat` with `AT_SYMLINK_NOFOLLOW`).** Deferred. v1 uses path-based best-effort cleanup with identity matching.
+- **Treating `PWD` as a protocol variable.** Rejected. Scripts that need a reliable cwd already have `process.cwd()` and `pwd -P`.
+- **`LOOPX_PROJECT_ROOT` canonicalization / `realpath`.** Rejected. Callers compute a realpath themselves if needed.
+- **Lockfile-based package-manager selection** (`bun install` for `bun.lockb`, `pnpm install` for `pnpm-lock.yaml`, etc.). Deferred. v1 uses `npm install` unconditionally; workflows needing a different manager pass `--no-install`. A later ADR may revisit when `packageManager`-field and lockfile-detection conventions have stabilized.
+- **Auto-install on `loopx run` when `node_modules/` is missing.** Rejected. `loopx run` is a hot loop-execution path; a silent `npm install` on first spawn would be surprising and would conflate install-time failures with run-time failures. The install-time auto-install in §6 is sufficient.
+- **`--ignore-scripts` by default for security.** Rejected. Many legitimate npm packages (native modules, CLI binaries with postinstall setup) require install scripts to function. Users installing from untrusted sources pass `--no-install` and inspect the workflow.
+- **Running `npm install` during staging instead of after commit.** Rejected. A staging-directory `node_modules/` may contain absolute-path artifacts from npm (bin shim scripts, cache paths, embedded metadata) that break when the staging directory is renamed into `.loopx/`. Post-commit installation operates on the final path.
+
+## Affected SPEC Sections
+
+When this ADR is accepted, the following SPEC sections require updates:
+
+- **§2.1 — Workflow structure (`package.json`).** Rewrite the "Dependency management" bullet: loopx auto-installs workflow dependencies via `npm install` during `loopx install` (see §10.10). At runtime, loopx does not re-install dependencies — a missing `node_modules/` at loop start surfaces as the active runtime's normal module resolution error when a script attempts to import. The `--no-install` flag on `loopx install` suppresses the install-time step for users who prefer manual control or a non-npm package manager.
+- **§3.2 — Project Root.** Clarify that the CLI's project root is `process.cwd()` at invocation (no `$PWD` consultation, no `realpath`) and the programmatic API's project root is `RunOptions.cwd` (resolved via `path.resolve(process.cwd(), options.cwd)` if relative, used unchanged if absolute; no further `realpath`) or `process.cwd()` at call time. Cross-reference §6.1 for the new script execution cwd and §9.5 for `RunOptions.cwd` type rules. The existing `LOOPX_DELEGATED` startup-reserved handling is unchanged.
+- **§3.3 — Module Resolution for Scripts.** Replace the "natural consequence of workflow-dir cwd" rationale with the actual rule: standard file-relative resolution of `"loopx"` from the importing module's path wins over the CLI fallback, independent of cwd. The custom Node/tsx resolve hook must preserve this — first attempt standard file-relative resolution (via `defaultResolve` delegation or equivalent), fall back to the CLI package exports only when standard resolution finds no `node_modules/loopx`. Note that Node's default main-module `realpath` canonicalization may cause the resolver to walk up from a canonical target when the entry path contains symlinks; workflow-local visibility at the symlinked logical path is not guaranteed in that case.
+- **§4.1 / §4.2 — CLI Grammar.** Record that v1 `loopx run` does not accept `--`, a named-argument tail, or any per-run-parameter CLI syntax outside the `run -h` / `--help` short-circuit. `--` in any non-help position is rejected as an unrecognized flag under the existing rejection rules. A sole positional `name=value` is parsed as a target string and fails target validation because `=` is not in the `[a-zA-Z0-9_][a-zA-Z0-9_-]*` pattern. The shell env prefix (`key=value loopx run <target>`) remains the sole CLI surface for per-run values. The `run -h` / `--help` short-circuit is unchanged. Add `--no-install` to the install-scoped options table: suppresses auto-install of workflow dependencies (§10.10). Duplicate `--no-install` is a usage error under the existing §4.2 duplicate-flag rule. The `install -h` / `--help` short-circuit continues to ignore `--no-install` unconditionally. No short form.
+- **§5.1 — Discovery.** Retarget the mid-loop removal/rename clause from "non-zero exit (section 7.2)" to "child launch / spawn failure (section 7.2)" to match §7.2's updated taxonomy. Clarify that discovery follows symlinks to determine entry types but preserves the discovered path spelling (no `realpath` applied); this extends to symlinked `.loopx` directories, symlinked `.loopx/<workflow>` directories, and symlinked entry script files.
+- **§6.1 — Working Directory.** Replace "all scripts run with the workflow directory as their working directory" with "all scripts run with `LOOPX_PROJECT_ROOT` as their working directory." Drop the "relative imports and `node_modules/` resolve naturally" rationale. Note that scripts remain free to `cd` / `process.chdir()`; such changes are scoped to that child process; later spawns start at project-root cwd. Record that loopx invokes each script using its absolute discovery-time path and does not canonicalize that path.
+- **§6.2 — Bash Scripts.** Note that the absolute discovery-time invocation path makes `$0` an absolute path, and `$(dirname "$0")` equals `LOOPX_WORKFLOW_DIR` byte-for-byte regardless of symlinks in the entry path (Bash does not canonicalize `$0`).
+- **§6.3 — JS/TS Scripts.** Note that `dirname(fileURLToPath(import.meta.url))` equals `LOOPX_WORKFLOW_DIR` only when the absolute entry path is symlink-free in every component. `LOOPX_WORKFLOW_DIR` is authoritative when a portable symlink-preserving workflow-directory handle is needed. loopx does not pass runtime-specific symlink-preservation flags.
+- **§7.1 — Pre-iteration sequence.** Insert `LOOPX_TMPDIR` creation between the starting workflow version check and the first child spawn. No tmpdir under `-n 0` / `maxIterations: 0`.
+- **§7.2 — Error Handling.** On `LOOPX_TMPDIR` creation failure, non-zero script exit, invalid / missing `goto` target, or child launch / spawn failure after tmpdir creation (discovered script removed or renamed per §5.1; runtime rejection of a child environment entry from any env tier, most reliably an entry with an embedded NUL byte; `exec` failure), the CLI exits `1` / `run()` throws on first iteration / `runPromise()` rejects. On tmpdir creation failure, best-effort cleanup runs on any partial directory without masking the creation error. On other error paths, `LOOPX_TMPDIR` cleanup runs before exit. Document cleanup idempotence: at most one cleanup attempt per created tmpdir over the lifetime of the run; racing terminal triggers do not re-attempt cleanup and do not re-emit warnings. Terminal-outcome precedence: except where an explicit precedence rule applies (pre-first-`next()` consumer-cancellation carve-out; abort-wins-over-pre-iteration; CLI pre-iteration signal-wins; abort-after-final-yield), the first terminal trigger observed by loopx determines the surfaced outcome among genuinely racing triggers; idempotence and warning cardinality are independent of outcome selection. Cleanup warning format is implementation-defined; at most one warning is emitted per run and cleanup warnings do not affect the CLI exit code, the generator outcome, or the promise rejection reason. Tmpdir location, mode, identity-fingerprint cleanup safety, symlink/non-directory/mismatched-directory/renamed-away handling, mount-point non-detection, and absence of stale-tmpdir reaping are specified in the new §7.4.
+- **§7.3 — Signal Handling.** On SIGINT / SIGTERM, `LOOPX_TMPDIR` cleanup runs after any active child process group has exited (per the existing grace period, including SIGKILL escalation) and before loopx exits with the signal's code. When no child is active, cleanup runs immediately. SIGINT / SIGTERM observed by loopx's installed pre-iteration signal handler wins over non-signal pre-iteration failures not yet surfaced at that point; loopx cleans up any partial tmpdir and exits with `128 + signal number`. Signals delivered before handler installation (process startup, argument parsing, help short-circuit) are outside this precedence — POSIX default disposition and parser-level usage-error exit `1` are both conforming outcomes.
+- **§7.4 — Run-scoped temporary directory lifecycle (new subsection).** Introduce a new §7.4 describing `LOOPX_TMPDIR` lifecycle end-to-end, covering:
+  - **Parent selection.** Tmpdir parent is `os.tmpdir()` evaluated in loopx's own process environment on the same schedule as the inherited `process.env` snapshot (synchronous at the `runPromise()` call site; at first `next()` for `run()`; pre-iteration for the CLI). `TMPDIR` / `TEMP` / `TMP` entries in env files or `RunOptions.env` reach spawned scripts but do not redirect the tmpdir parent.
+  - **Location, naming, and mode.** Created under the selected parent via `mkdtemp` with a `loopx-` prefix, mode `0700`. Exact name format beyond the prefix is implementation-defined.
+  - **Creation order.** `mkdtemp` → identity fingerprint capture → mode verification / securing, in that order, before any child is exposed to the path. Per-step failure handling determines cleanup:
+    - `mkdtemp` failure: no path exists; no cleanup.
+    - Identity capture failure: single non-recursive `rmdir`, outside the race-resistant guarantee (see below).
+    - Mode-securing failure: full identity-fingerprint cleanup-safety routine.
+  - **Identity-fingerprint cleanup safety.** Cleanup `lstat`s the path and dispatches: ENOENT → no-op; symlink → unlink entry, do not follow target; non-directory non-symlink → leave in place with a warning; directory with matching identity → recursively remove, unlinking (not traversing) symlink entries encountered during the walk; directory with mismatched identity → leave in place with a warning. Top-level `lstat` failures (other than ENOENT), case-2 `unlink` failures, and case-4 recursive-removal failures emit a single stderr warning and halt further changes.
+  - **Renamed-away and mount-point behavior.** Scripts that remove or rename the tmpdir during the run defeat automatic cleanup of the moved directory; loopx does not chase renamed tmpdirs. loopx does not detect or avoid mount points inside `$LOOPX_TMPDIR`; scripts that mount into the tmpdir are responsible for unmounting before cleanup.
+  - **Race-resistance scope.** Path-based best-effort cleanup with identity matching is guaranteed; a race-resistant guarantee against a same-user process actively mutating the path during cleanup (fd-relative `openat` / `unlinkat` with `AT_SYMLINK_NOFOLLOW`) is out of scope for v1.
+  - **No stale-tmpdir reaping at startup.** Leaked tmpdirs from prior SIGKILL / host-crash terminations are expected to be reaped by OS temp-cleaning policy.
+  - **Settlement-based cleanup on `run()` normal completion.** Cleanup is guaranteed only once the generator is driven to settlement; a caller that consumes the final yielded `Output` and abandons the generator may leak the tmpdir.
+- **§8 — Environment Variables.** Add `LOOPX_TMPDIR` and `LOOPX_WORKFLOW_DIR` to the injected-variables table. `LOOPX_WORKFLOW_DIR` is the absolute path of the currently-spawned script's workflow directory and refreshes per-spawn alongside `LOOPX_WORKFLOW`. Document that `RunOptions.env` merges after env files and before loopx-injected protocol variables. Extend the existing "env files are loaded once at loop start and cached" rule (§8.1) to also cover inherited `process.env`: it is snapshotted once during the pre-iteration sequence and reused for every child spawn in the run; mutations between spawns do not propagate. The tmpdir parent (the `TMPDIR` / `TEMP` / `TMP` values read by `os.tmpdir()` in loopx's own process) is captured on the same schedule as the inherited-env snapshot; see §7.4. Rewrite the §8.3 precedence list (highest wins) to five tiers:
+  1. loopx-injected protocol variables (`LOOPX_BIN`, `LOOPX_PROJECT_ROOT`, `LOOPX_WORKFLOW`, `LOOPX_WORKFLOW_DIR`, `LOOPX_TMPDIR`)
+  2. `RunOptions.env`
+  3. Local env file (`-e` / `RunOptions.envFile`)
+  4. Global loopx env file (`$XDG_CONFIG_HOME/loopx/env`)
+  5. Inherited system environment (snapshotted once per run)
+- **§9.1 / §9.2 — Programmatic API.** Document the new `env` option: call-time shallow copy, merge position, rejection on invalid shape, ignored when omitted. Document that inherited `process.env` is snapshotted once per run — lazy for `run()` (captured at first `next()` alongside the rest of the pre-iteration sequence, so mutations between `run()` returning and first `next()` **are** observed), synchronous at call time for `runPromise()` (captured before `runPromise()` returns; mutations after return are not observed). The tmpdir parent (the `TMPDIR` / `TEMP` / `TMP` values that `os.tmpdir()` reads) is captured on the same schedule as the inherited `process.env` snapshot, so a synchronous `process.env.TMPDIR = …` mutation after `runPromise()` returns does not affect the tmpdir parent, and a mutation between `run()` returning and first `next()` **does** affect it. Document `LOOPX_TMPDIR` creation timing (lazy — first `next()` for `run()`, asynchronous after return for `runPromise()`) and cleanup under abort and consumer-driven cancellation. Document validation rules for invalid `options` (must be omitted, `undefined`, or a non-null non-array non-function object); invalid `options.signal` (must be `AbortSignal`-compatible with readable `aborted` and callable `addEventListener`; `removeEventListener` is not required); invalid `options.cwd` / `options.envFile` (must be strings when present); and duck-typed signal reentrancy (signal treated as aborted if `addEventListener` synchronously invokes the listener or `aborted` is observed as `true` at any point during call-time capture; real `AbortSignal` instances already aborted must be observed as aborted regardless of implementation latitude). Document options-snapshot ordering: `options.signal` read first; order of remaining fields implementation-defined; each field read at most once per call; throwing getters not re-invoked. Qualify SPEC §9.1's "aborting the signal always produces an error, even if it occurs before the first `next()` call" with the pre-first-`next()` consumer-cancellation carve-out: a `.return()` / `.throw()` as the consumer's first interaction on a `run()` generator settles per standard JS async-generator semantics; the generator body is never entered, and no pre-iteration error (captured option-snapshot, invalid / target-syntax `target`, `.loopx/` discovery, env-file loading, target resolution, tmpdir creation) and no captured signal state surface. This carve-out applies only to `run()`; `runPromise()` has no equivalent.
+- **§9.3 — Error Behavior.** Extend the rejection / throw surface to cover `LOOPX_TMPDIR` creation failure; child launch / spawn failure after tmpdir creation (including runtime env-entry rejections from any tier); `RunOptions.env` shape and snapshot-time errors (invalid shape, throwing `ownKeys` trap, throwing enumerable getter, throwing `options.env` getter); invalid `options` and invalid `options.signal`; and non-string `options.cwd` / `options.envFile` (including throwing getters). Document that cleanup runs before the generator throws or the promise rejects, so cleanup ordering is observable from the caller, and that cleanup warnings do not mask the original rejection reason. Document abort precedence across pre-iteration: once a usable `AbortSignal` has been captured, an already-aborted or mid-pre-iteration abort wins over later option-field validation, target argument / target syntax validation, `.loopx/` discovery, env-file loading, target resolution, and tmpdir-creation errors. An invalid `options` value or non-`AbortSignal`-compatible `options.signal` captures no signal and does not enter this pathway. Document the pinned programmatic pre-iteration priority: project-root-blocking and envFile-path-blocking option errors (non-string `options.cwd` / `options.envFile`, or throwing getters) surface before the four project-root-dependent failures (`.loopx/` discovery, env-file loading, target resolution, tmpdir creation); relative priority between these pinned errors and target validation, and priority among other non-abort pre-iteration errors, is implementation-defined. Document the abort-after-final-yield rule: an abort observed after the final `Output` yield but before generator settlement becomes the terminal outcome on the next generator interaction.
+- **§9.5 — Types.** Add `env?: Record<string, string>` to `RunOptions`. Update `cwd?: string` prose: `cwd` now specifies both the project root and the script execution cwd. Document that `cwd` and `envFile`, when present and not `undefined`, must be strings; non-string values are captured at call time and surfaced via the pre-iteration error path. A relative `cwd` is resolved via `path.resolve(process.cwd(), options.cwd)` at call time with no further `realpath`; an absolute `cwd` is used unchanged. Drop the prior "cwd does not control script execution cwd" disclaimer. Preserve the existing relative-`envFile` rule restated for the new `cwd` meaning: a relative `envFile` resolves against the resolved project root (equal to the child's cwd) when `cwd` is supplied, and against the caller's `process.cwd()` at call time otherwise.
+- **§10.7 — Install Atomicity.** Clarify that the section's atomicity scope covers only the file-level install (source acquisition → preflight → stage → commit). Post-commit auto-install behaviors specified in §10.10 (`.gitignore` safeguard synthesis, `npm install`) run after the commit phase and are outside §10.7's preflight-atomicity guarantee: they do not roll back committed workflow files. The "preflight-atomic" invariant and stage-then-commit mechanics themselves are unchanged; only the scope boundary is made explicit, with a forward pointer to §10.10 for post-commit failure semantics.
+- **§10.9 — Common Rules.** Remove the bullet "loopx does not run `npm install` or `bun install` after cloning/extracting. For workflows with dependencies, the user must install them manually …" — this behavior is retired and replaced by §10.10. Narrow the "Install failure cleanup" bullet so its partial-directory-removal-on-exit contract applies only to the pre-commit failure modes enumerated in that bullet (download error, HTTP non-2xx, git clone failure, extraction failure, post-download validation failure) plus any §10.7 staging-phase failure. Explicitly note that post-commit auto-install failures under §10.10 (`.gitignore` write failures, `npm install` non-zero exit, `npm install` spawn failure) still cause exit `1` but do **not** remove already-committed workflow directories from `.loopx/` and do **not** remove a partial `node_modules/` left behind by an interrupted install; those behaviors are governed by §10.10's aggregate-report / no-rollback rule. Add a cross-reference from the "Install failure cleanup" bullet to §10.10 so the reader is routed to the post-commit failure semantics.
+- **§10.10 — Auto-install workflow dependencies (new subsection).** After the commit phase, loopx spawns `npm install` sequentially in each committed workflow that contains a top-level `package.json`, with cwd set to the workflow directory. Cover: trigger conditions; unconditional use of `npm install` (no lockfile/packageManager-field detection; no loopx-added flags); environment inheritance from loopx's own `process.env` without `LOOPX_*` / `RunOptions.env` / env-file injection; stdout and stderr passthrough; `--no-install` opt-out; failure behavior (continue to next workflow, aggregate-report, exit `1`, no file-level rollback — explicitly scoped out of §10.7 atomicity and §10.9 partial-directory cleanup); malformed-`package.json` skip (same §3.2 failure modes already warn, no second warning); `-w` and `-y` interactions; signal handling (propagate to npm child, wait for exit, skip remaining workflows, no `node_modules/` cleanup); install-hook trust profile. Also cover the `.gitignore` safeguard: immediately before spawning `npm install`, loopx creates a `.gitignore` containing the single line `node_modules` in the workflow directory if and only if no `.gitignore` already exists there; a pre-existing `.gitignore` is left unchanged regardless of its contents; `.gitignore` creation is skipped under the same conditions that skip `npm install` (`--no-install`, missing top-level `package.json`, malformed `package.json`); a `.gitignore` write failure **skips `npm install` for that workflow** (the safeguard is a precondition for running `npm install`, not a parallel step), loopx proceeds to the next workflow, and the failure aggregates with `npm install` failures to contribute to the final exit `1`.
+- **§11.3 — Install Help.** Update the documented install options from `(-w, -y)` to `(-w, -y, --no-install)` so install help surfaces the new flag. The "install help does not require a source argument, does not make network requests, and does not inspect `.loopx/`" clause is unchanged, and the `install -h` / `--help` short-circuit continues to ignore `--no-install` unconditionally.
+- **§12 — Exit Codes.** Extend the code-`1` enumeration to cover `LOOPX_TMPDIR` creation failure, child launch / spawn failure after tmpdir creation, and the two auto-install failure modes during `loopx install`: (a) `npm install` failure (non-zero exit or spawn failure) and (b) `.gitignore` safeguard write failure (which skips `npm install` for that workflow and aggregates per §10.10). Signal exit codes remain `128 + N`; `LOOPX_TMPDIR` cleanup runs before exit under signals, and a signal received during `npm install` causes loopx to wait for the npm child to exit before exiting with the signal's code. Cleanup warnings do not affect the exit code or the programmatic outcome.
+- **§13 — Reserved Values.** Add `LOOPX_TMPDIR` and `LOOPX_WORKFLOW_DIR` as reserved env var names in the script-protocol-protected role (injected on every child spawn; silently override any user-supplied value at the §8.3 top tier). Clarify that the reserved list covers two distinct roles:
+  - **Script-protocol-protected** (injected on every child spawn, overrides user values at §8.3 top tier): `LOOPX_BIN`, `LOOPX_PROJECT_ROOT`, `LOOPX_WORKFLOW`, `LOOPX_WORKFLOW_DIR`, `LOOPX_TMPDIR`.
+  - **Startup-reserved only** (inspected on loopx's own startup — e.g., as a delegation recursion guard per SPEC §3.2 — but not injected or protected on per-spawn script environments): `LOOPX_DELEGATED`.
+
+  The `LOOPX_DELEGATED` table entry should be updated to reflect the startup-reserved-only role explicitly. `PWD` is not added to the reserved list in either role.
+
+## Test Recommendations
+
+Non-exhaustive — these highlight a few edge cases easy to overlook. A full test plan belongs in TEST-SPEC.md after this ADR is accepted.
+
+- **Tmpdir cleanup under racing terminal triggers.** Verify at most one cleanup attempt — and therefore at most one cleanup warning — for a run when multiple terminal triggers arrive (e.g., SIGTERM followed by SIGINT during cleanup; abort concurrent with consumer `.return()` / `.throw()`; non-zero exit concurrent with abort; abort observed after final yield followed by `.throw()`).
+- **Cleanup safety under path replacement.** Symlink replacement unlinked without following the target; non-directory non-symlink replacement left in place; mismatched-identity directory left in place; renamed-away tmpdir not chased; hard-link `nlink` of a shared inode unchanged after cleanup.
+- **Pre-first-`next()` consumer cancellation carve-out.** A `.return()` / `.throw()` as the consumer's first interaction on a `run()` generator suppresses every pre-iteration error (captured option-snapshot, invalid / target-syntax `target`, missing `.loopx/` / discovery, env-file loading, target resolution, tmpdir creation) and any already-aborted signal. The tight scope matters: the same errors surface on first `next()`, and a `.return()` / `.throw()` after first `next()` follows normal consumer-driven-cancellation rules.
+- **Abort wins over pre-iteration failures when a usable signal is captured.** An already-aborted `AbortSignal` passed alongside an invalid target, missing `.loopx/`, invalid `env` shape, or a throwing option-field getter read *after* `options.signal` surfaces the abort error on first `next()`. A non-compatible `options.signal` captures no signal and surfaces as an ordinary option-snapshot error, not as an abort.
+- **Abort after final yield.** A consumer that manually iterates to the final yielded `Output` and then aborts before calling `next()` again observes the abort error on the subsequent `next()` — not `{ done: true }`. Cleanup runs before the abort error is surfaced.
+- **Inherited-env snapshot timing split.** For `run()`, a `process.env` mutation between `run()` returning and the first `next()` **is** observed by every child; later mutations between iterations are not. For `runPromise()`, the snapshot is taken before return, so a synchronous `process.env` mutation after `runPromise()` returns is not observed. `RunOptions.env` is captured at call time under both APIs.
+- **Tmpdir-parent snapshot timing.** The tmpdir parent is captured on the same schedule as the inherited-env snapshot: a synchronous `process.env.TMPDIR = …` mutation after `runPromise()` returns does not affect the tmpdir parent for that run, while a mutation between `run()` returning and first `next()` does. `TMPDIR` / `TEMP` / `TMP` entries in env files or `RunOptions.env` do not redirect the tmpdir parent under either API.
+- **`RunOptions.env` precedence and shape validation.** Entries override same-named values from `-e`, the global env file, and inherited `process.env`, and are overridden by protocol variables. Invalid shapes (`env: null`, `env: []`, non-string values, function values) reject under `maxIterations: 0` without a spawn; the CLI has no `RunOptions.env` surface, so `-n 0` does not exercise this shape-validation path. Runtime-level rejections (NUL-byte entries) surface only at spawn time, so they require `maxIterations >= 1` programmatically or `-n >= 1` on the CLI.
+- **CLI grammar.** `loopx run -- <target>`, `loopx run -n 1 -- <target>`, `loopx run <target> -- name=value`, and `loopx run <target> name=value` each exit `1` as usage errors. `loopx run name=value` from a directory with `.loopx/` fails target validation; from a directory without `.loopx/` surfaces the discovery error first. `name=value loopx run <target>` succeeds (the shell absorbs the prefix). The `run -h` / `--help` short-circuit ignores `--`, extra positionals, and `name=value` tokens in any position.
+- **Project-root cwd and workflow-dir injection.** The same effective working directory (device/inode) is observed across the starting target, `goto` destinations, and loop reset; project-root-relative references (`cat SPEC.md`) resolve without `$LOOPX_PROJECT_ROOT`. `LOOPX_WORKFLOW_DIR` refreshes per-spawn across cross-workflow `goto` A → B (the B-side script sees B's directory). Under a canonical, symlink-free entry path, Bash `$(dirname "$0")` equals `LOOPX_WORKFLOW_DIR` byte-for-byte; under symlinks in any component of the absolute entry path, the Bash equality still holds (Bash does not canonicalize `$0`) but JS/TS `dirname(fileURLToPath(import.meta.url))` equality is not required.
+- **Auto-install triggers only on `package.json` presence.** A workflow with a top-level `package.json` has `node_modules/` populated after `loopx install` completes. A workflow without a top-level `package.json` produces no `npm install` invocation and no warning; its install completes at the same speed as pre-ADR. A workflow whose `package.json` lives in a subdirectory (not at the workflow root) is also skipped.
+- **`--no-install` opt-out.** `loopx install --no-install <source>` commits workflow files but does not invoke `npm install`; `node_modules/` is absent after the install. Duplicate `--no-install` is a usage error (exit 1). `loopx install -h --no-install` shows install help and exits 0.
+- **Auto-install failure handling.** An `npm install` exit non-zero or spawn failure (e.g., `npm` not on `PATH`) causes `loopx install` to exit `1` but leaves committed workflow files on disk. A subsequent `loopx install -y <source>` fully re-runs the install and re-runs `npm install`. For a multi-workflow install where workflow A's `npm install` fails and workflow B's succeeds, both workflows remain committed to `.loopx/`, B has a populated `node_modules/`, A does not, and loopx exits `1` with an aggregate report naming A.
+- **Malformed `package.json` suppresses both version check and auto-install.** A workflow whose `package.json` is unreadable, contains invalid JSON, or has an invalid `loopx` semver range emits the single §3.2 warning; `npm install` is not invoked against it; no second warning is emitted. `loopx install` still exits `0` (other workflows succeeding and no `npm install` having failed for this one).
+- **Signal during `npm install`.** SIGINT delivered while an `npm install` child is running causes loopx to wait for the child to exit, skip the remaining committed workflows' `npm install`, and exit `130` (or the appropriate `128 + N`). Committed workflow files and any partial `node_modules/` produced by the interrupted npm child remain on disk.
+- **`-y` replacement refreshes `node_modules/`.** `loopx install -y <source>` against an existing workflow whose `.loopx/<name>/node_modules/` contains stale dependencies removes the entire old workflow directory and re-runs `npm install` against the replacement's `package.json`.
+- **`.gitignore` safeguard.** A workflow with a top-level `package.json` and no `.gitignore` in the source has a `.gitignore` containing the single line `node_modules` after `loopx install` completes. A workflow shipping its own `.gitignore` (empty, minimal, or containing unrelated patterns) has that file preserved byte-for-byte — loopx does not append `node_modules` to it. `loopx install --no-install <source>` against a workflow with a `package.json` and no `.gitignore` does not create one. A workflow without a top-level `package.json` is never touched. Under `-y` replacement, the replacement's `.gitignore` (or absence thereof) applies — any previously synthesized `.gitignore` is removed with the old workflow directory and re-synthesized only if the replacement still has no `.gitignore`.
diff --git a/adr/0004-tmpdir-and-env.md b/adr/0004-tmpdir-and-env.md
deleted file mode 100644
index 6d1938a..0000000
--- a/adr/0004-tmpdir-and-env.md
+++ /dev/null
@@ -1,168 +0,0 @@
-# ADR-0004: Run-Scoped Temporary Directory and Programmatic Env Option
-
-**Status:** Proposed
-
----
-
-## Decision Summary
-
-- **`LOOPX_TMPDIR`.** Each `loopx run` gets a private `os.tmpdir()`-based directory (mode `0700`), injected into every script's env. Shared across iterations, cleaned up on terminal outcomes (normal completion, error exit, signal, abort).
-- **`RunOptions.env`.** A new optional `Record<string, string>` field on `RunOptions`, shallow-merged into the child env between env-file loading and loopx protocol variable injection.
-- **No CLI named-argument syntax.** CLI callers who want to pass a per-run value use the standard shell env-var prefix (`key=value loopx run …`), which already flows through loopx's env inheritance. `-e` and `loopx env set` remain available for file-based config.
-- **Cleanup safety.** Path-based best-effort: loopx does not follow symlinks and does not delete files or directories that replaced the tmpdir after creation. Not a sandbox against actively racing same-user processes.
-
-A later ADR may revisit a first-class CLI named-argument surface, a named-argument schema, or stronger race-resistant cleanup (e.g., `openat` / `unlinkat`) if evidence of need accumulates.
-
----
-
-## Context
-
-Two pain points have emerged as workflows have grown.
-
-1. **Passing intermediate data between scripts during a loop run.** Workflows like `review-adr`, `apply-adr`, and `spec-test-adr` stash hand-off files (`.feedback.tmp`, `.claude-output.tmp`, `.answer.tmp`, `.prompt.tmp`) either inside their own workflow directory or in a sibling `.loopx/shared/` directory — the latter so scripts reached via cross-workflow `goto` can find them at `$ROOT/.loopx/$LOOPX_WORKFLOW/…` after the goto. Both patterns rely on `rm -f` on the happy path with no cleanup on error, signal, or unexpected termination; leaked files accumulate and are indistinguishable from legitimate workflow content. The `ralph` workflow has the same issue with its hand-maintained `.loopx/.iteration.tmp` counter — intra-run state that has been leaking into the `.loopx/` directory because there is no per-run scratch space to hold it.
-
-2. **Per-run parameterization from programmatic callers.** Callers of `run()` / `runPromise()` currently have no way to inject per-invocation env vars without mutating `process.env` globally, which is racy under concurrent calls. The CLI already handles the parameterization case natively — `adr=0003 loopx run review-adr` works today because `src/env.ts` spreads inherited `process.env` into the child — but the programmatic API has no equivalent.
-
-An earlier draft of this ADR proposed a `loopx run … -- name=value` CLI surface with its own precedence tier and dedicated parser. It is intentionally not adopted: for the identified use case (passing a parameter like an ADR number into a script), shell env-var prefixing on the CLI is already sufficient, and the parser surface would add substantial implementation complexity (two-phase parsing, name grammar, duplicate detection, `LOOPX_*` reservation, precedence tier reordering) without matching value for v1. Scripts that need to validate a required value do so themselves (`: "${adr:?need adr}"` in Bash; `if (!process.env.adr) throw …` in TS).
-
-A generic session-state mechanism (first-class iteration counter, key-value store) was considered but deferred. Scripts that need such state maintain it inside `$LOOPX_TMPDIR` — including the iteration counter, which is a trivial read/increment/write against a file there.
-
-## Decision
-
-### 1. `LOOPX_TMPDIR` — run-scoped temporary directory
-
-For each `loopx run` (CLI) or `run()` / `runPromise()` (programmatic) invocation that reaches execution, loopx creates a unique temporary directory before the first child process spawns and injects its absolute path into every script's environment as `LOOPX_TMPDIR`.
-
-#### Location, naming, and mode
-
-The directory is created under Node's `os.tmpdir()` via `mkdtemp` with a `loopx-` prefix. Mode is `0700` (owner read/write/execute only). The exact name format beyond the prefix is implementation-defined and must not be relied on by scripts.
-
-#### Scope and lifecycle
-
-- **Created:** once per run, after pre-iteration validation (discovery, env loading, target resolution, version check) and immediately before the first child spawns. Pre-spawn failures, `-n 0` / `maxIterations: 0` early exits, and aborts observed before tmpdir creation do not create a tmpdir.
-- **Shared across iterations.** All scripts in the run — the starting target, scripts reached via intra-workflow `goto`, scripts reached via cross-workflow `goto`, and re-executions of the starting target on loop reset — observe the same `LOOPX_TMPDIR` value.
-- **Persisted within the run.** The directory is not cleared between iterations. Files written by one script remain visible to later scripts in the same run.
-- **Concurrent runs are isolated.** Each `loopx run` invocation receives its own distinct directory. Parallel runs of the same workflow do not share temporary state.
-- **Not created under `-n 0` / `maxIterations: 0`.** No child process is spawned, so no tmpdir is created and `LOOPX_TMPDIR` is not injected into any environment.
-
-#### Cleanup
-
-loopx runs cleanup of the tmpdir on every terminal outcome of a run that reached tmpdir creation:
-
-- **Normal completion:** `stop: true` from a script, or `-n` / `maxIterations` reached.
-- **Error exit:** non-zero script exit, invalid `goto` target, missing workflow or missing script during a `goto` resolution.
-- **SIGINT / SIGTERM to loopx:** if a child process group is active, cleanup runs after the process group exits (per SPEC §7.3, including `SIGKILL` escalation to the process group if required) and before loopx exits with the signal's exit code. If no child is active when the signal arrives (including the window after tmpdir creation but before the first child spawns, and the window between one child exiting and the next spawning), cleanup runs immediately.
-- **Programmatic `AbortSignal` abort:** if a child process group is active, loopx first terminates it per SPEC §9.1; cleanup runs after the process group exits, before the generator throws or the promise rejects. If the abort fires while no child is active, cleanup runs eagerly from loopx's signal listener and the next generator interaction (or the outstanding `runPromise()` promise) settles with the abort error as soon as cleanup completes.
-- **Consumer-driven cancellation under `run()`** (`break` from `for await`, explicit `generator.return()`, explicit `generator.throw(err)` after the first `next()`): loopx terminates any active child per SPEC §9.1, runs cleanup, then settles the generator (`{ done: true }` for `break` / `.return()`; throws `err` for `.throw(err)`).
-
-Cleanup does **not** run when loopx itself is killed via SIGKILL or the host crashes; leaked tmpdirs are expected to be reaped by OS temp-cleaning policy (`systemd-tmpfiles`, tmpfs reboot). loopx does not attempt to reap stale tmpdirs at startup.
-
-If cleanup fails, loopx prints a single warning to stderr. The CLI exit code, generator outcome, and promise rejection reason are unchanged.
-
-#### Cleanup safety
-
-Cleanup is path-based and best-effort — not a sandbox against actively racing same-user processes. loopx captures the created directory's device/inode pair at creation time, before any child is exposed to the directory. At cleanup time loopx `lstat`s the `LOOPX_TMPDIR` path and dispatches:
-
-1. **Path no longer exists:** no-op.
-2. **Path is a symlink:** unlink the symlink entry; do not traverse or follow the target. Unlinking a symlink affects only the symlink entry itself.
-3. **Path is a regular file, FIFO, socket, or other non-directory non-symlink:** leave in place with a single stderr warning. Unlinking such replacements is unsafe because a hard link would decrement a shared inode's `nlink`, and data renamed into the path has `nlink == 1` — in both cases `unlink` would mutate unrelated data.
-4. **Path is a directory with matching device/inode identity:** recursively remove. Symlink entries encountered during the walk are unlinked but not traversed, so symlinks pointing outside the tmpdir do not collateral-delete their targets.
-5. **Path is a directory whose identity does not match the recorded identity:** leave in place with a single stderr warning. loopx does not recursively remove a directory it did not create.
-
-A script that removes or renames its tmpdir during the run defeats automatic cleanup of the moved directory; loopx does not chase renamed tmpdirs.
-
-This guarantee covers script-introduced replacements that are quiescent by the time cleanup begins. It is not a race-resistant guarantee against a same-user process that mutates the path during cleanup itself; a stronger guarantee (fd-relative `openat` / `unlinkat` with `AT_SYMLINK_NOFOLLOW`) is out of scope for v1.
-
-#### Creation failure
-
-If the underlying `mkdtemp`, identity-capture, or mode-securing operation fails (e.g., `EACCES`, `ENOSPC`, `EMFILE`), loopx does not spawn any child. The CLI exits `1` with a stderr error; `run()` throws on the first iteration; `runPromise()` rejects.
-
-If a partial directory exists when the failure is detected, loopx attempts best-effort cleanup of it subject to the safety rules above (recursive cleanup requires a recorded identity; if identity capture itself failed, cleanup is limited to non-traversing actions). Failure of that best-effort cleanup prints an additional stderr warning but does not mask the original creation-failure error.
-
-If a SIGINT/SIGTERM or `AbortSignal` abort arrives concurrently with a creation failure, the signal/abort wins — the creation failure is not surfaced as the terminal outcome — and any partial directory is cleaned up under the same rules.
-
-#### Programmatic API (`run()` / `runPromise()`)
-
-Tmpdir creation is lazy under both APIs. Neither creates a tmpdir at the call site of `run()` or `runPromise()`. The pre-iteration sequence (field validation, discovery, env loading, target resolution, version check) runs on the first `next()` call for `run()` and asynchronously after return for `runPromise()`; tmpdir creation follows that sequence immediately before the first child spawns.
-
-A generator returned by `run()` that is never iterated (no `next()`, no `.return()`, no `.throw()`) performs no pre-iteration work and creates no tmpdir. Pre-first-`next()` `generator.return(value)` or `generator.throw(err)` settles the generator immediately per standard JS async-generator semantics without creating a tmpdir.
-
-Once created, the tmpdir is cleaned up whenever the generator settles terminally or the promise settles. Callers who drive `run()` via `for await (...)` or who use `runPromise()` observe cleanup automatically. Callers who manually consume `next()` and then abandon the generator without calling `.return()` or driving it to completion may leak a tmpdir until the generator is garbage-collected — a JS-language limitation, not a loopx guarantee.
-
-### 2. `RunOptions.env`
-
-`RunOptions` gains an optional `env` field:
-
-```typescript
-interface RunOptions {
-  maxIterations?: number;
-  envFile?: string;
-  signal?: AbortSignal;
-  cwd?: string;
-  env?: Record<string, string>;
-}
-```
-
-- **Shape.** `env` must be omitted, `undefined`, or a non-null, non-array object whose own enumerable string-keyed entries all have string values. Invalid shapes (null, array, non-object, or an entry with a non-string value) are rejected via the standard pre-iteration error path: `run()` throws on the first `next()`; `runPromise()` rejects. Symbol-keyed, non-enumerable, and inherited properties are ignored — not iterated, not validated, not forwarded.
-- **Merge position.** `env` entries are merged into the child environment *after* global and local env-file loading and *before* loopx-injected protocol variables (`LOOPX_BIN`, `LOOPX_PROJECT_ROOT`, `LOOPX_WORKFLOW`, `LOOPX_TMPDIR`). A `RunOptions.env` entry therefore overrides same-named values from `-e`, the global loopx env file, and inherited `process.env`, and is itself overridden by protocol variables. This slots into the existing merge in `src/execution.ts` between the merged-env layer and the loopx-injected layer.
-- **Lifetime.** Entries are captured at call time via `Object.keys(env)` as a shallow copy. Mutating the original object after `run()` / `runPromise()` returns has no effect on the running loop.
-- **Applies to every script in the run.** The starting target, `goto` destinations (intra- and cross-workflow), and loop resets to the starting target all receive the same `env` additions.
-- **No CLI surface.** `env` is programmatic-only. CLI callers pass per-run values via the shell env prefix (`key=value loopx run …`), which flows through inherited `process.env`, or via `-e` / `loopx env set` for file-based config.
-- **No name validation beyond "must be a string-to-string entry."** loopx does not enforce the POSIX `[A-Za-z_][A-Za-z0-9_]*` env-name pattern, does not reject `LOOPX_*` keys, and does not reject NUL-byte values. A key the OS rejects surfaces as a spawn failure; a `LOOPX_*` key that collides with a protocol variable is silently overridden by protocol injection (which runs after `env`).
-
-## Consequences
-
-- **Workflow directories stop accumulating temp files.** Existing workflows migrate `.feedback.tmp` / `.claude-output.tmp` / `.answer.tmp` / `.prompt.tmp` / `ralph`'s `.iteration.tmp` into `$LOOPX_TMPDIR/…` and drop their manual `rm -f` branches. Workflow directories contain only version-controlled scripts and static assets.
-- **Cleanup is automatic on failure.** Loops that error out, are signaled, or are aborted no longer leak scratch files. Callers who relied on lingering `.tmp` files for post-mortem inspection must write those outside `$LOOPX_TMPDIR` (for example, under `$LOOPX_PROJECT_ROOT`).
-- **Cross-run state is the caller's responsibility.** `LOOPX_TMPDIR` never persists across runs. A workflow that genuinely needs cross-run state (a long-lived counter, a cache surviving across invocations) uses `$LOOPX_PROJECT_ROOT`-relative storage. `ralph`'s `.iteration.tmp` is **not** an example of cross-run state — it is intra-run state leaking into the workflow directory, and should migrate to `$LOOPX_TMPDIR/iteration`.
-- **Concurrent runs are safe.** Parallel `loopx run` invocations of the same workflow do not clobber each other's scratch files, which was previously possible with in-workflow `.tmp` files.
-- **Programmatic callers get per-run env without mutating `process.env`.** Previously the only way to inject a per-run value programmatically was to mutate `process.env` before calling `run()`, which is racy under concurrent calls. `RunOptions.env` is a clean shallow copy scoped to the call.
-- **CLI parameterization uses existing shell idioms.** `adr=0003 loopx run review-adr` works today and continues to work. Users who want override precedence over `-e` or global env for a single CLI invocation use `-e` or `loopx env set` explicitly; loopx does not provide a CLI-level override tier for one-shot values.
-- **No named-argument schema.** Workflows do not declare expected input names, types, defaults, or requiredness. Scripts validate their own inputs. A schema mechanism may be introduced in a later ADR if the unchecked-input model proves insufficient.
-- **No first-class iteration counter.** Workflows maintain one in `$LOOPX_TMPDIR/iteration` if needed. A first-class counter may be introduced later.
-- **Migration is manual but straightforward.** Existing `review-adr`, `apply-adr`, and `spec-test-adr` workflows replace in-workflow `.tmp` paths with `$LOOPX_TMPDIR/…`, drop `rm -f` cleanup, and take their per-run parameter via shell env prefix (e.g., `adr=0003 loopx run review-adr`). No automated migration tooling is provided.
-
-## Affected SPEC Sections
-
-When this ADR is accepted, the following SPEC sections require updates:
-
-- **§3.2 / §7.1 — Pre-iteration sequence.** Insert `LOOPX_TMPDIR` creation between the starting workflow version check and the first child spawn. Under `-n 0` / `maxIterations: 0`, no tmpdir is created.
-- **§7.2 — Error Handling.** On non-zero script exit or invalid / missing `goto` target, `LOOPX_TMPDIR` cleanup runs after the error is detected and before loopx exits `1`.
-- **§7.3 — Signal Handling.** On SIGINT / SIGTERM, `LOOPX_TMPDIR` cleanup runs after any active child process group has exited (per the existing grace period) and before loopx exits with the signal's code. When no child is active when the signal arrives, cleanup runs immediately. Signals that arrive before tmpdir creation require no cleanup.
-- **§8 — Environment Variables.** Add `LOOPX_TMPDIR` to the injected-variables table. Document that `RunOptions.env` merges after env files (global + local) and before loopx-injected protocol variables.
-- **§9.1 / §9.2 — Programmatic API.** Document the new `env` option: its call-time shallow-copy, its merge position, its rejection on invalid shape, and that it is ignored when omitted. Document `LOOPX_TMPDIR` creation timing (lazy — on first `next()` for `run()`, asynchronous after return for `runPromise()`) and cleanup under abort and consumer-driven cancellation.
-- **§9.5 — Types.** Add `env?: Record<string, string>` to `RunOptions`.
-- **§13 — Reserved Values.** Add `LOOPX_TMPDIR` as a reserved env var name.
-
-## Test Recommendations
-
-Non-exhaustive — these highlight edge cases that are easy to overlook.
-
-### `LOOPX_TMPDIR`
-
-- `LOOPX_TMPDIR` is injected with an absolute path; its basename begins with `loopx-` and lives under `os.tmpdir()`.
-- Same value is observed across the starting target, intra-workflow `goto`, cross-workflow `goto`, and loop reset to the starting target.
-- Files written by one script are visible to subsequent scripts in the same run.
-- Parallel `loopx run` invocations receive distinct paths and distinct directories.
-- Directory mode is `0700`.
-- Cleanup runs on each terminal outcome: normal completion (`stop: true` and `maxIterations` reached), non-zero script exit, invalid `goto` target, SIGINT/SIGTERM (including between iterations and between tmpdir creation and first spawn), `AbortSignal` abort (including mid-iteration, between iterations, and after the final yield but before `{ done: true }`), `break` from `for await`, explicit `generator.return()` after first `next()`, explicit `generator.throw(err)` after first `next()`.
-- Cleanup of a symlink inside `$LOOPX_TMPDIR` pointing outside: symlink entry is unlinked, target is untouched.
-- Cleanup when the tmpdir path has been replaced: symlink replacement is unlinked (target untouched); regular-file / FIFO / socket replacement is left in place with a warning; mismatched-identity directory replacement is left in place with a warning; renamed-away tmpdir is left at its new path without being chased.
-- Hard-link safety: a script that creates a hard link at the tmpdir path to unrelated data leaves the link count of the shared inode unchanged after cleanup, and the unrelated target file is untouched.
-- Rename-into-path safety: a script that renames an unrelated file into the tmpdir path leaves the file's data intact after cleanup.
-- Cleanup failure prints a single stderr warning and does not change the CLI exit code, generator outcome, or promise rejection reason.
-- Under `-n 0` / `maxIterations: 0`, no tmpdir is created.
-- When pre-spawn validation fails (discovery error, env-file error, target-resolution error) or an `AbortSignal` is already aborted before tmpdir creation, no tmpdir is created.
-- When tmpdir creation itself fails after producing a partial directory, best-effort cleanup runs on the partial directory without masking the original creation error.
-- A user-supplied `LOOPX_TMPDIR` in inherited env, the `-e` local env file, the global env file, or `RunOptions.env` is overridden by the injected protocol value.
-
-### `RunOptions.env`
-
-- `run(target, { env: { adr: "0003" } })` results in `process.env.adr === "0003"` inside the script, and `$adr == "0003"` in a Bash script.
-- Same `env` applied to every iteration, every `goto` destination, and every loop reset.
-- Overrides same-named entries from `-e` local env file, global loopx env file, and inherited `process.env`.
-- Overridden by loopx protocol variables: `env: { LOOPX_TMPDIR: "/fake" }` is not observable in the child.
-- `run(target, { env: undefined })`, `run(target, { env: {} })`, and `run(target, {})` all inject no additional entries.
-- Invalid shapes reject on first iteration (for `run()`) or via promise rejection (for `runPromise()`): `env: null`, `env: []`, `env: "nope"`, `env: 42`, `env: { x: 42 }` (non-string value).
-- Mutating the original `env` object after `run()` / `runPromise()` returns does not affect the running loop (call-time shallow copy).
-- Symbol-keyed, non-enumerable, and inherited properties of `env` are ignored — neither validated nor forwarded.
diff --git a/loopx-backup/apply-adr/apply-answer.sh b/loopx-backup/apply-adr/apply-answer.sh
deleted file mode 100755
index d406614..0000000
--- a/loopx-backup/apply-adr/apply-answer.sh
+++ /dev/null
@@ -1,23 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-ROOT="$LOOPX_PROJECT_ROOT"
-CLAUDE_OUTPUT_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.claude-output.tmp"
-ANSWER_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.answer.tmp"
-
-if [[ ! -f "$ANSWER_FILE" ]]; then
-  echo "Error: No answer file found at $ANSWER_FILE" >&2
-  exit 1
-fi
-
-ANSWER=$(cat "$ANSWER_FILE")
-
-# Continue the existing conversation started by apply-feedback
-CLAUDE_OUTPUT=$(echo "$ANSWER" | claude --dangerously-skip-permissions -c -p 2>/dev/null)
-
-echo "$CLAUDE_OUTPUT" > "$CLAUDE_OUTPUT_FILE"
-rm -f "$ANSWER_FILE"
-
-echo "=== Claude processed the answer ===" >&2
-
-$LOOPX_BIN output --goto "check-question"
diff --git a/loopx-backup/apply-adr/apply-feedback.sh b/loopx-backup/apply-adr/apply-feedback.sh
deleted file mode 100755
index 72bb173..0000000
--- a/loopx-backup/apply-adr/apply-feedback.sh
+++ /dev/null
@@ -1,28 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-ROOT="$LOOPX_PROJECT_ROOT"
-FEEDBACK_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.feedback.tmp"
-CLAUDE_OUTPUT_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.claude-output.tmp"
-
-if [[ ! -f "$FEEDBACK_FILE" ]]; then
-  echo "Error: No feedback file found at $FEEDBACK_FILE" >&2
-  exit 1
-fi
-
-FEEDBACK=$(cat "$FEEDBACK_FILE")
-
-PROMPT="ADR-0002 has been accepted and I am now updating SPEC.md to incorporate its changes (per the ADR process in ADR-0001). I received the following feedback on the current state of SPEC.md. Read adr/0002-run-subcommand.md (accepted — read-only reference) and SPEC.md (target of updates) yourself before acting. Apply this feedback by updating SPEC.md only. ADR-0002 is the authoritative reference for what should change — do not modify it. If there is any ambiguity about my intentions, ask me clarifying questions. Think critically about this feedback and push back if warranted. After you finish, commit and push.
-
-Feedback:
-$FEEDBACK"
-
-CLAUDE_OUTPUT=$(echo "$PROMPT" | claude --dangerously-skip-permissions -p 2>/dev/null)
-
-rm -f "$FEEDBACK_FILE"
-echo "$CLAUDE_OUTPUT" > "$CLAUDE_OUTPUT_FILE"
-
-echo "" >&2
-echo "=== Claude finished applying feedback ===" >&2
-
-$LOOPX_BIN output --goto "check-question"
diff --git a/loopx-backup/apply-adr/check-question.schema.json b/loopx-backup/apply-adr/check-question.schema.json
deleted file mode 100644
index fe39a58..0000000
--- a/loopx-backup/apply-adr/check-question.schema.json
+++ /dev/null
@@ -1,11 +0,0 @@
-{
-  "type": "object",
-  "properties": {
-    "has_question": {
-      "description": "true if the text contains a question or request for clarification directed at the user, false otherwise",
-      "type": "boolean"
-    }
-  },
-  "required": ["has_question"],
-  "additionalProperties": false
-}
diff --git a/loopx-backup/apply-adr/check-question.sh b/loopx-backup/apply-adr/check-question.sh
deleted file mode 100755
index 45d4306..0000000
--- a/loopx-backup/apply-adr/check-question.sh
+++ /dev/null
@@ -1,121 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-ROOT="$LOOPX_PROJECT_ROOT"
-CLAUDE_OUTPUT_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.claude-output.tmp"
-ANSWER_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.answer.tmp"
-
-: "${TELEGRAM_BOT_TOKEN:?TELEGRAM_BOT_TOKEN env var is required}"
-: "${TELEGRAM_CHAT_ID:?TELEGRAM_CHAT_ID env var is required}"
-
-TELEGRAM_API="https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}"
-
-if [[ ! -f "$CLAUDE_OUTPUT_FILE" ]]; then
-  echo "Error: No Claude output file found at $CLAUDE_OUTPUT_FILE" >&2
-  exit 1
-fi
-
-CLAUDE_OUTPUT=$(cat "$CLAUDE_OUTPUT_FILE")
-
-# Use Codex with output schema to deterministically classify the output
-SCHEMA="$ROOT/.loopx/$LOOPX_WORKFLOW/check-question.schema.json"
-VERDICT=$(codex exec --output-schema "$SCHEMA" "Does the following text contain a question or request for clarification directed at the user?
-
-$CLAUDE_OUTPUT" 2>/dev/null)
-
-HAS_QUESTION=$(echo "$VERDICT" | jq -r '.has_question')
-
-if [[ "$HAS_QUESTION" == "true" ]]; then
-  echo "=== Claude has a question — sending to Telegram ===" >&2
-
-  # Send as document if too long for a message, otherwise as text
-  if [[ ${#CLAUDE_OUTPUT} -gt 4000 ]]; then
-    QUESTION_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.question.tmp"
-    echo "$CLAUDE_OUTPUT" > "$QUESTION_FILE"
-    curl -s -X POST "${TELEGRAM_API}/sendDocument" \
-      -F chat_id="$TELEGRAM_CHAT_ID" \
-      -F document=@"$QUESTION_FILE;filename=question.md" \
-      -F caption="Claude has a question — reply with your answer" > /dev/null
-    rm -f "$QUESTION_FILE"
-  else
-    curl -s -X POST "${TELEGRAM_API}/sendMessage" \
-      -d chat_id="$TELEGRAM_CHAT_ID" \
-      --data-urlencode "text=${CLAUDE_OUTPUT}" > /dev/null
-  fi
-
-  echo "Waiting for answer..." >&2
-
-  # Flush old updates to get current offset
-  FLUSH_RESPONSE=$(curl -s "${TELEGRAM_API}/getUpdates?offset=-1")
-  LAST_UPDATE_ID=$(echo "$FLUSH_RESPONSE" | jq -r '.result[-1].update_id // empty')
-  if [[ -n "$LAST_UPDATE_ID" ]]; then
-    OFFSET=$((LAST_UPDATE_ID + 1))
-  else
-    OFFSET=0
-  fi
-
-  # Long-poll for a reply, collecting split messages over a 10s window
-  COLLECTED=""
-  DEADLINE=""
-
-  while true; do
-    if [[ -n "$DEADLINE" ]]; then
-      NOW=$(date +%s)
-      if [[ $NOW -ge $DEADLINE ]]; then
-        break
-      fi
-      POLL_TIMEOUT=2
-    else
-      POLL_TIMEOUT=30
-    fi
-
-    UPDATES=$(curl -s "${TELEGRAM_API}/getUpdates?offset=${OFFSET}&timeout=${POLL_TIMEOUT}")
-
-    MSG_COUNT=$(echo "$UPDATES" | jq --arg cid "$TELEGRAM_CHAT_ID" '
-      [.result[] | select(.message.chat.id == ($cid | tonumber) and .message.text != null)] | length
-    ')
-
-    if [[ "$MSG_COUNT" -gt 0 ]]; then
-      NEW_TEXTS=$(echo "$UPDATES" | jq -r --arg cid "$TELEGRAM_CHAT_ID" '
-        [.result[] | select(.message.chat.id == ($cid | tonumber) and .message.text != null)]
-        | .[].message.text
-      ')
-      if [[ -n "$COLLECTED" ]]; then
-        COLLECTED="${COLLECTED}
-${NEW_TEXTS}"
-      else
-        COLLECTED="$NEW_TEXTS"
-      fi
-
-      if [[ -z "$DEADLINE" ]]; then
-        DEADLINE=$(( $(date +%s) + 10 ))
-        echo "=== First message received, collecting for 10s... ===" >&2
-      fi
-    fi
-
-    NEW_LAST=$(echo "$UPDATES" | jq -r '.result[-1].update_id // empty')
-    if [[ -n "$NEW_LAST" ]]; then
-      OFFSET=$((NEW_LAST + 1))
-    fi
-  done
-
-  curl -s "${TELEGRAM_API}/getUpdates?offset=${OFFSET}" > /dev/null
-
-  echo "$COLLECTED" > "$ANSWER_FILE"
-  echo "=== Answer received from Telegram ===" >&2
-  echo "--- Begin answer ---" >&2
-  echo "$COLLECTED" >&2
-  echo "--- End answer ---" >&2
-
-  $LOOPX_BIN output --goto "apply-answer"
-  exit 0
-else
-  # No question — notify and loop back to copy-prompt
-  curl -s -X POST "${TELEGRAM_API}/sendMessage" \
-    -d chat_id="$TELEGRAM_CHAT_ID" \
-    -d text="Feedback applied. Ready for next review cycle." > /dev/null
-
-  rm -f "$CLAUDE_OUTPUT_FILE"
-  echo "=== No questions. Ready for next review cycle. ===" >&2
-  $LOOPX_BIN output --result "Feedback applied. Ready for next review cycle."
-fi
diff --git a/loopx-backup/apply-adr/index.sh b/loopx-backup/apply-adr/index.sh
deleted file mode 100755
index e2d05c2..0000000
--- a/loopx-backup/apply-adr/index.sh
+++ /dev/null
@@ -1,55 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-ROOT="$LOOPX_PROJECT_ROOT"
-ADR_0001="$ROOT/adr/0001-adr-process.md"
-ADR_0002="$ROOT/adr/0002-run-subcommand.md"
-SPEC="$ROOT/SPEC.md"
-PROMPT_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.prompt.tmp"
-
-if [[ ! -f "$ADR_0001" ]]; then
-  echo "Error: adr/0001-adr-process.md not found" >&2
-  exit 1
-fi
-
-if [[ ! -f "$ADR_0002" ]]; then
-  echo "Error: adr/0002-run-subcommand.md not found" >&2
-  exit 1
-fi
-
-if [[ ! -f "$SPEC" ]]; then
-  echo "Error: SPEC.md not found" >&2
-  exit 1
-fi
-
-# Build the prompt and save to file (too long for a single Telegram message)
-cat <<PROMPT > "$PROMPT_FILE"
-ADR 0002 has been accepted. The next step in the process is to update SPEC.md to incorporate the changes described in ADR 0002. Review the current SPEC.md against ADR 0002 and let me know if the SPEC updates look correct and complete, or if anything else in the SPEC needs to be changed.
-
-adr/0002-run-subcommand.md (accepted — do not modify):
-$(cat "$ADR_0002")
-
-SPEC.md (target of updates):
-$(cat "$SPEC")
-PROMPT
-
-MODE="${LOOPX_REVIEWER:-telegram}"
-case "$MODE" in
-  telegram)
-    exec ./lib/send-telegram.sh
-    ;;
-  codex)
-    exec ./lib/send-codex.sh
-    ;;
-  api)
-    if [[ ! -x ./node_modules/.bin/tsx ]]; then
-      echo "Error: ./node_modules/.bin/tsx not found. Run 'npm install' in $(pwd) to enable LOOPX_REVIEWER=api." >&2
-      exit 1
-    fi
-    exec ./node_modules/.bin/tsx ./lib/send-api.ts
-    ;;
-  *)
-    echo "Error: unknown LOOPX_REVIEWER='$MODE' (expected unset, 'telegram', 'codex', or 'api')" >&2
-    exit 1
-    ;;
-esac
diff --git a/loopx-backup/apply-adr/lib/send-api.ts b/loopx-backup/apply-adr/lib/send-api.ts
deleted file mode 100644
index ebdd380..0000000
--- a/loopx-backup/apply-adr/lib/send-api.ts
+++ /dev/null
@@ -1,106 +0,0 @@
-import OpenAI, { toFile } from "openai";
-import { readFileSync, writeFileSync, rmSync, existsSync } from "node:fs";
-import { randomUUID } from "node:crypto";
-import { execFileSync } from "node:child_process";
-
-const ROOT = process.env.LOOPX_PROJECT_ROOT!;
-const WORKFLOW = process.env.LOOPX_WORKFLOW!;
-const BIN = process.env.LOOPX_BIN!;
-const THINKING = (process.env.GPT_PRO_THINKING ?? "medium") as
-  | "medium"
-  | "high"
-  | "xhigh";
-
-if (!process.env.OPENAI_API_KEY) {
-  console.error(
-    "OPENAI_API_KEY is required. Set via: loopx env set OPENAI_API_KEY <key>",
-  );
-  process.exit(1);
-}
-
-const PROMPT_FILE = `${ROOT}/.loopx/${WORKFLOW}/.prompt.tmp`;
-const FEEDBACK_FILE = `${ROOT}/.loopx/${WORKFLOW}/.feedback.tmp`;
-
-if (!existsSync(PROMPT_FILE)) {
-  console.error(`Error: prompt file not found at ${PROMPT_FILE}`);
-  process.exit(1);
-}
-
-const prompt = readFileSync(PROMPT_FILE, "utf8");
-
-if (existsSync(FEEDBACK_FILE)) rmSync(FEEDBACK_FILE);
-
-const client = new OpenAI();
-
-const batchLine = JSON.stringify({
-  custom_id: `gpt54-${randomUUID()}`,
-  method: "POST",
-  url: "/v1/responses",
-  body: {
-    model: "gpt-5.4-pro",
-    reasoning: { effort: THINKING },
-    input: prompt,
-  },
-});
-
-const inputFile = await client.files.create({
-  file: await toFile(
-    Buffer.from(batchLine + "\n", "utf8"),
-    `batch-${Date.now()}.jsonl`,
-    { type: "application/x-ndjson" },
-  ),
-  purpose: "batch",
-});
-
-const batch = await client.batches.create({
-  input_file_id: inputFile.id,
-  endpoint: "/v1/responses",
-  completion_window: "24h",
-});
-
-console.error(`submitted batch: ${batch.id}`);
-
-let b = batch;
-let lastStatus: string | undefined;
-while (
-  !b.output_file_id &&
-  !b.error_file_id &&
-  !["failed", "expired", "cancelled"].includes(b.status)
-) {
-  await new Promise((r) => setTimeout(r, 2000));
-  b = await client.batches.retrieve(batch.id);
-  if (b.status !== lastStatus) {
-    console.error(`waiting for batch ${b.id} (${b.status})...`);
-    lastStatus = b.status;
-  }
-}
-
-if (b.error_file_id) {
-  const err = await (await client.files.content(b.error_file_id)).text();
-  throw new Error(`Batch error: ${err}`);
-}
-if (!b.output_file_id) {
-  throw new Error(`Batch ${batch.id} ended in status ${b.status}`);
-}
-
-const outText = await (await client.files.content(b.output_file_id)).text();
-const line = JSON.parse(outText.trim().split(/\r?\n/)[0]);
-if (line.error) throw new Error(`Batch error: ${line.error.message}`);
-
-const resp = line.response.body as { output_text?: string; output?: any[] };
-const answer =
-  resp.output_text ??
-  (resp.output ?? [])
-    .filter((o: any) => o.type === "message")
-    .flatMap((o: any) => o.content ?? [])
-    .filter((c: any) => c.type === "output_text")
-    .map((c: any) => c.text)
-    .join("\n");
-
-writeFileSync(FEEDBACK_FILE, answer);
-rmSync(PROMPT_FILE);
-console.error("=== Feedback received from GPT-5.4-Pro ===");
-
-execFileSync(BIN, ["output", "--goto", "apply-feedback"], {
-  stdio: "inherit",
-});
diff --git a/loopx-backup/apply-adr/lib/send-codex.sh b/loopx-backup/apply-adr/lib/send-codex.sh
deleted file mode 100755
index 9f98df8..0000000
--- a/loopx-backup/apply-adr/lib/send-codex.sh
+++ /dev/null
@@ -1,43 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-ROOT="$LOOPX_PROJECT_ROOT"
-PROMPT_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.prompt.tmp"
-FEEDBACK_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.feedback.tmp"
-
-if ! command -v codex >/dev/null 2>&1; then
-  echo "Error: codex CLI not found on PATH" >&2
-  exit 1
-fi
-
-if [[ ! -s "$PROMPT_FILE" ]]; then
-  echo "Error: prompt file not found at $PROMPT_FILE" >&2
-  exit 1
-fi
-
-echo "" >&2
-echo "=== Invoking codex CLI ===" >&2
-
-rm -f "$FEEDBACK_FILE"
-
-codex exec - \
-  --skip-git-repo-check \
-  --sandbox read-only \
-  --color never \
-  --output-last-message "$FEEDBACK_FILE" \
-  < "$PROMPT_FILE" >/dev/null
-
-rm -f "$PROMPT_FILE"
-
-if [[ ! -s "$FEEDBACK_FILE" ]]; then
-  echo "Error: codex produced no feedback" >&2
-  exit 1
-fi
-
-echo "=== Feedback received from codex ===" >&2
-echo "--- Begin feedback ---" >&2
-cat "$FEEDBACK_FILE" >&2
-echo "" >&2
-echo "--- End feedback ---" >&2
-
-$LOOPX_BIN output --goto "apply-feedback"
diff --git a/loopx-backup/apply-adr/lib/send-telegram.sh b/loopx-backup/apply-adr/lib/send-telegram.sh
deleted file mode 100755
index 9ecf963..0000000
--- a/loopx-backup/apply-adr/lib/send-telegram.sh
+++ /dev/null
@@ -1,104 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-ROOT="$LOOPX_PROJECT_ROOT"
-PROMPT_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.prompt.tmp"
-FEEDBACK_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.feedback.tmp"
-
-: "${TELEGRAM_BOT_TOKEN:?TELEGRAM_BOT_TOKEN env var is required}"
-: "${TELEGRAM_CHAT_ID:?TELEGRAM_CHAT_ID env var is required}"
-
-if [[ ! -s "$PROMPT_FILE" ]]; then
-  echo "Error: prompt file not found at $PROMPT_FILE" >&2
-  exit 1
-fi
-
-TELEGRAM_API="https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}"
-
-# Flush old updates to get current offset
-FLUSH_RESPONSE=$(curl -s "${TELEGRAM_API}/getUpdates?offset=-1")
-LAST_UPDATE_ID=$(echo "$FLUSH_RESPONSE" | jq -r '.result[-1].update_id // empty')
-if [[ -n "$LAST_UPDATE_ID" ]]; then
-  OFFSET=$((LAST_UPDATE_ID + 1))
-else
-  OFFSET=0
-fi
-
-# Send the prompt as a document attachment
-SEND_RESPONSE=$(curl -s -X POST "${TELEGRAM_API}/sendDocument" \
-  -F chat_id="$TELEGRAM_CHAT_ID" \
-  -F document=@"$PROMPT_FILE;filename=review-prompt.md" \
-  -F caption="Review prompt — reply with your feedback")
-
-SENT_OK=$(echo "$SEND_RESPONSE" | jq -r '.ok')
-if [[ "$SENT_OK" != "true" ]]; then
-  echo "Error: Failed to send Telegram message: $SEND_RESPONSE" >&2
-  rm -f "$PROMPT_FILE"
-  exit 1
-fi
-
-rm -f "$PROMPT_FILE"
-
-echo "" >&2
-echo "=== Prompt sent to Telegram ===" >&2
-echo "Reply in the Telegram chat with your feedback." >&2
-echo "Waiting for reply..." >&2
-
-# Long-poll for a reply, collecting split messages over a 10s window
-COLLECTED=""
-DEADLINE=""
-
-while true; do
-  # After first message arrives, switch to short polls and enforce deadline
-  if [[ -n "$DEADLINE" ]]; then
-    NOW=$(date +%s)
-    if [[ $NOW -ge $DEADLINE ]]; then
-      break
-    fi
-    POLL_TIMEOUT=2
-  else
-    POLL_TIMEOUT=30
-  fi
-
-  UPDATES=$(curl -s "${TELEGRAM_API}/getUpdates?offset=${OFFSET}&timeout=${POLL_TIMEOUT}")
-
-  MSG_COUNT=$(echo "$UPDATES" | jq --arg cid "$TELEGRAM_CHAT_ID" '
-    [.result[] | select(.message.chat.id == ($cid | tonumber) and .message.text != null)] | length
-  ')
-
-  if [[ "$MSG_COUNT" -gt 0 ]]; then
-    NEW_TEXTS=$(echo "$UPDATES" | jq -r --arg cid "$TELEGRAM_CHAT_ID" '
-      [.result[] | select(.message.chat.id == ($cid | tonumber) and .message.text != null)]
-      | .[].message.text
-    ')
-    if [[ -n "$COLLECTED" ]]; then
-      COLLECTED="${COLLECTED}
-${NEW_TEXTS}"
-    else
-      COLLECTED="$NEW_TEXTS"
-    fi
-
-    # Start 10s collection window on first message
-    if [[ -z "$DEADLINE" ]]; then
-      DEADLINE=$(( $(date +%s) + 10 ))
-      echo "=== First message received, collecting for 10s... ===" >&2
-    fi
-  fi
-
-  # Advance offset past all updates
-  NEW_LAST=$(echo "$UPDATES" | jq -r '.result[-1].update_id // empty')
-  if [[ -n "$NEW_LAST" ]]; then
-    OFFSET=$((NEW_LAST + 1))
-  fi
-done
-
-# Acknowledge all collected updates
-curl -s "${TELEGRAM_API}/getUpdates?offset=${OFFSET}" > /dev/null
-
-echo "$COLLECTED" > "$FEEDBACK_FILE"
-echo "=== Feedback received from Telegram ===" >&2
-echo "--- Begin feedback ---" >&2
-echo "$COLLECTED" >&2
-echo "--- End feedback ---" >&2
-
-$LOOPX_BIN output --goto "apply-feedback"
diff --git a/loopx-backup/apply-adr/package.json b/loopx-backup/apply-adr/package.json
deleted file mode 100644
index 025b36b..0000000
--- a/loopx-backup/apply-adr/package.json
+++ /dev/null
@@ -1,7 +0,0 @@
-{
-  "type": "module",
-  "dependencies": {
-    "openai": "^6.0.0",
-    "tsx": "^4.19.3"
-  }
-}
diff --git a/loopx-backup/package.json b/loopx-backup/package.json
deleted file mode 100644
index 089153b..0000000
--- a/loopx-backup/package.json
+++ /dev/null
@@ -1 +0,0 @@
-{"type":"module"}
diff --git a/loopx-backup/ralph/check-ready.sh b/loopx-backup/ralph/check-ready.sh
deleted file mode 100755
index 7d40193..0000000
--- a/loopx-backup/ralph/check-ready.sh
+++ /dev/null
@@ -1,33 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-ROOT="$LOOPX_PROJECT_ROOT"
-ITER_FILE="$ROOT/.loopx/.iteration.tmp"
-
-: "${TELEGRAM_BOT_TOKEN:?TELEGRAM_BOT_TOKEN env var is required}"
-: "${TELEGRAM_CHAT_ID:?TELEGRAM_CHAT_ID env var is required}"
-
-TELEGRAM_API="https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}"
-
-RALPH_OUTPUT=$(cat)
-
-REVIEW_PROMPT=$(printf 'The following is the stdout of one iteration of an agent development loop. Judge whether the output itself states or clearly indicates that the work is production ready / complete / done. Only answer READY if the output affirmatively claims production readiness. Reply with exactly one word: READY or NOT_READY.\n\n--- begin output ---\n%s\n--- end output ---' "$RALPH_OUTPUT")
-
-VERDICT=$(echo "$REVIEW_PROMPT" | claude -p --dangerously-skip-permissions 2>/dev/null)
-
-echo "=== Readiness verdict: ${VERDICT} ===" >&2
-
-if echo "$VERDICT" | grep -qw "READY"; then
-  ITER=$(cat "$ITER_FILE" 2>/dev/null || echo "?")
-
-  curl -s -X POST "${TELEGRAM_API}/sendMessage" \
-    -d chat_id="$TELEGRAM_CHAT_ID" \
-    --data-urlencode "text=Ralph loop: production ready after iteration ${ITER}. Halting." > /dev/null
-
-  rm -f "$ITER_FILE"
-  echo "=== Production ready — halting loop ===" >&2
-  $LOOPX_BIN output --result "Production ready after iteration ${ITER}." --stop
-else
-  echo "=== Not production ready — continuing loop ===" >&2
-  $LOOPX_BIN output --result "continuing" --goto "index"
-fi
diff --git a/loopx-backup/ralph/index.sh b/loopx-backup/ralph/index.sh
deleted file mode 100755
index 80398a5..0000000
--- a/loopx-backup/ralph/index.sh
+++ /dev/null
@@ -1,33 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-ROOT="$LOOPX_PROJECT_ROOT"
-PROMPT_FILE="$ROOT/PROMPT.md"
-ITER_FILE="$ROOT/.loopx/.iteration.tmp"
-
-: "${TELEGRAM_BOT_TOKEN:?TELEGRAM_BOT_TOKEN env var is required}"
-: "${TELEGRAM_CHAT_ID:?TELEGRAM_CHAT_ID env var is required}"
-
-TELEGRAM_API="https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}"
-
-if [[ ! -f "$PROMPT_FILE" ]]; then
-  echo "Error: PROMPT.md not found at $PROMPT_FILE" >&2
-  exit 1
-fi
-
-if [[ -f "$ITER_FILE" ]]; then
-  ITER=$(($(cat "$ITER_FILE") + 1))
-else
-  ITER=1
-fi
-echo "$ITER" > "$ITER_FILE"
-
-curl -s -X POST "${TELEGRAM_API}/sendMessage" \
-  -d chat_id="$TELEGRAM_CHAT_ID" \
-  --data-urlencode "text=Ralph loop: starting iteration ${ITER}" > /dev/null
-
-echo "=== Ralph iteration ${ITER} ===" >&2
-
-RALPH_OUTPUT=$(cat "$PROMPT_FILE" | claude -p --dangerously-skip-permissions 2>/dev/null)
-
-$LOOPX_BIN output --result "$RALPH_OUTPUT" --goto "check-ready"
diff --git a/loopx-backup/ralph/package.json b/loopx-backup/ralph/package.json
deleted file mode 100644
index 089153b..0000000
--- a/loopx-backup/ralph/package.json
+++ /dev/null
@@ -1 +0,0 @@
-{"type":"module"}
diff --git a/loopx-backup/review-adr/.claude-output.tmp b/loopx-backup/review-adr/.claude-output.tmp
deleted file mode 100644
index 041c51e..0000000
--- a/loopx-backup/review-adr/.claude-output.tmp
+++ /dev/null
@@ -1,36 +0,0 @@
-I've read ADR-0004 in full, SPEC §9.1, and ADR-0001. Before I make changes, I need to push back on parts of the feedback and clarify your intent on the genuinely ambiguous ones.
-
-## Where I agree with the reviewer
-
-- **Blocker 1 (snapshot timing):** Real. Line 67 (step 1 of programmatic pre-iteration) says loopx "snapshots `env`'s own enumerable string-keyed entries via `Object.keys(env)`" — as if snapshotting happens at step 1 (first iteration). But line 322, line 370, and tests at lines 559–560 all say snapshotting happens at call time. SPEC §9.1 also says "`run()` snapshots its options and `cwd` at call time." Call-time is clearly the intent; line 67 is just imprecise wording. I can align line 67 without asking.
-- **Stale `args?: string[]` reference (line 410):** Confirmed — SPEC.md has no such field. I'll remove that sentence.
-
-## Where I'd push back
-
-- **Clarifying Q3 (broader scope freeze is intentional?):** Already answered. The Decision Summary (lines 7–21) itemizes 8 normative commitments including options-shape validation, same-realm AbortSignal, and abort-dominance-over-`.return()`/`.throw()`. The Scope note at line 38 explicitly says these are in scope. A reviewer reading the ADR cannot accept it without encountering these. I don't think anything further needs to be said — unless you want me to cross-reference the Decision Summary from the scope note to double-signal.
-- **Clarifying Q4 (unrestricted env-overlay intentional?):** Already answered in the Decision Summary bullet (line 12) and section 2 "Scope of the feature" (line 196).
-- **Clarifying Q5 (same-realm-only AbortSignal intentional?):** Already answered at line 67 with two sentences of rationale and a bridging recommendation.
-
-For these three, the reviewer is asking you to confirm things the ADR already explicitly commits to. I don't plan to add more text unless you want me to.
-
-## Where I need your input
-
-**Question 1 — Accessor / getter / proxy behavior under call-time snapshotting.**
-Once we lock in "snapshot at call time", a throwing getter or proxy trap could make `run()` throw synchronously — which would conflict with SPEC §9.1's "`run()` call itself always returns a generator without throwing". Three options:
-
-- **(A)** Snapshot happens at call time; any synchronous throw during capture (getter throws, proxy `ownKeys`/`get` trap throws) is caught and surfaced lazily on first iteration as a step-1 field-validation error. Preserves the "always returns a generator" invariant.
-- **(B)** Snapshot happens at call time; throws from accessors/proxies propagate synchronously from `run()`. Cleaner for callers using plain objects but breaks the SPEC §9.1 invariant for the accessor edge case.
-- **(C)** Narrow accepted `env` to plain objects (prototype must be `Object.prototype` or `null`), rejecting proxies and accessor-having objects at step 1.
-
-I'd recommend **(A)**. It preserves SPEC §9.1, keeps the current permissive object-model contract, and is testable ("constructed `env` with a throwing getter surfaces lazily"). Do you want (A), (B), or (C)?
-
-**Question 2 — Title broadening.**
-Current title: "Run-Scoped Temporary Directory, Named Run Arguments, and **Pre-spawn** Cancellation Semantics". "Pre-spawn" literally excludes the abort-wins-until-terminal-settlement, consumer `.return()`/`.throw()`, and post-final-yield rules, which are iteration-time. Options:
-
-- Keep as is (rely on Decision Summary to carry the scope signal)
-- Broaden to "…and Programmatic Run Lifecycle" (covers pre-spawn, iteration, and final-yield window)
-- Broaden to "…and Programmatic Run Cancellation and Validation Semantics"
-
-Which do you want?
-
-Once you answer these two, I'll make the full edit pass, commit, and push.
diff --git a/loopx-backup/review-adr/apply-answer.sh b/loopx-backup/review-adr/apply-answer.sh
deleted file mode 100755
index d406614..0000000
--- a/loopx-backup/review-adr/apply-answer.sh
+++ /dev/null
@@ -1,23 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-ROOT="$LOOPX_PROJECT_ROOT"
-CLAUDE_OUTPUT_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.claude-output.tmp"
-ANSWER_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.answer.tmp"
-
-if [[ ! -f "$ANSWER_FILE" ]]; then
-  echo "Error: No answer file found at $ANSWER_FILE" >&2
-  exit 1
-fi
-
-ANSWER=$(cat "$ANSWER_FILE")
-
-# Continue the existing conversation started by apply-feedback
-CLAUDE_OUTPUT=$(echo "$ANSWER" | claude --dangerously-skip-permissions -c -p 2>/dev/null)
-
-echo "$CLAUDE_OUTPUT" > "$CLAUDE_OUTPUT_FILE"
-rm -f "$ANSWER_FILE"
-
-echo "=== Claude processed the answer ===" >&2
-
-$LOOPX_BIN output --goto "check-question"
diff --git a/loopx-backup/review-adr/apply-feedback.sh b/loopx-backup/review-adr/apply-feedback.sh
deleted file mode 100755
index 490e144..0000000
--- a/loopx-backup/review-adr/apply-feedback.sh
+++ /dev/null
@@ -1,28 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-ROOT="$LOOPX_PROJECT_ROOT"
-FEEDBACK_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.feedback.tmp"
-CLAUDE_OUTPUT_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.claude-output.tmp"
-
-if [[ ! -f "$FEEDBACK_FILE" ]]; then
-  echo "Error: No feedback file found at $FEEDBACK_FILE" >&2
-  exit 1
-fi
-
-FEEDBACK=$(cat "$FEEDBACK_FILE")
-
-PROMPT="I received the following feedback about ADR-0004 (run-scoped tmpdir and script args proposal) and its relationship to SPEC.md as defined by the the process laid out in ADR-0001. Incorporate this feedback to improve ADR-0004. If there is any ambiguity about my intentions, ask me clarifying questions. Think critically about this feedback and push back if warranted. Do not update any file other than ADR-0004 and do not mark it as accepted. After you finish, commit and push.
-
-Feedback:
-$FEEDBACK"
-
-CLAUDE_OUTPUT=$(echo "$PROMPT" | claude --dangerously-skip-permissions -p 2>/dev/null)
-
-rm -f "$FEEDBACK_FILE"
-echo "$CLAUDE_OUTPUT" > "$CLAUDE_OUTPUT_FILE"
-
-echo "" >&2
-echo "=== Claude finished applying feedback ===" >&2
-
-$LOOPX_BIN output --goto "check-question"
diff --git a/loopx-backup/review-adr/check-question.schema.json b/loopx-backup/review-adr/check-question.schema.json
deleted file mode 100644
index fe39a58..0000000
--- a/loopx-backup/review-adr/check-question.schema.json
+++ /dev/null
@@ -1,11 +0,0 @@
-{
-  "type": "object",
-  "properties": {
-    "has_question": {
-      "description": "true if the text contains a question or request for clarification directed at the user, false otherwise",
-      "type": "boolean"
-    }
-  },
-  "required": ["has_question"],
-  "additionalProperties": false
-}
diff --git a/loopx-backup/review-adr/check-question.sh b/loopx-backup/review-adr/check-question.sh
deleted file mode 100755
index 45d4306..0000000
--- a/loopx-backup/review-adr/check-question.sh
+++ /dev/null
@@ -1,121 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-ROOT="$LOOPX_PROJECT_ROOT"
-CLAUDE_OUTPUT_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.claude-output.tmp"
-ANSWER_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.answer.tmp"
-
-: "${TELEGRAM_BOT_TOKEN:?TELEGRAM_BOT_TOKEN env var is required}"
-: "${TELEGRAM_CHAT_ID:?TELEGRAM_CHAT_ID env var is required}"
-
-TELEGRAM_API="https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}"
-
-if [[ ! -f "$CLAUDE_OUTPUT_FILE" ]]; then
-  echo "Error: No Claude output file found at $CLAUDE_OUTPUT_FILE" >&2
-  exit 1
-fi
-
-CLAUDE_OUTPUT=$(cat "$CLAUDE_OUTPUT_FILE")
-
-# Use Codex with output schema to deterministically classify the output
-SCHEMA="$ROOT/.loopx/$LOOPX_WORKFLOW/check-question.schema.json"
-VERDICT=$(codex exec --output-schema "$SCHEMA" "Does the following text contain a question or request for clarification directed at the user?
-
-$CLAUDE_OUTPUT" 2>/dev/null)
-
-HAS_QUESTION=$(echo "$VERDICT" | jq -r '.has_question')
-
-if [[ "$HAS_QUESTION" == "true" ]]; then
-  echo "=== Claude has a question — sending to Telegram ===" >&2
-
-  # Send as document if too long for a message, otherwise as text
-  if [[ ${#CLAUDE_OUTPUT} -gt 4000 ]]; then
-    QUESTION_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.question.tmp"
-    echo "$CLAUDE_OUTPUT" > "$QUESTION_FILE"
-    curl -s -X POST "${TELEGRAM_API}/sendDocument" \
-      -F chat_id="$TELEGRAM_CHAT_ID" \
-      -F document=@"$QUESTION_FILE;filename=question.md" \
-      -F caption="Claude has a question — reply with your answer" > /dev/null
-    rm -f "$QUESTION_FILE"
-  else
-    curl -s -X POST "${TELEGRAM_API}/sendMessage" \
-      -d chat_id="$TELEGRAM_CHAT_ID" \
-      --data-urlencode "text=${CLAUDE_OUTPUT}" > /dev/null
-  fi
-
-  echo "Waiting for answer..." >&2
-
-  # Flush old updates to get current offset
-  FLUSH_RESPONSE=$(curl -s "${TELEGRAM_API}/getUpdates?offset=-1")
-  LAST_UPDATE_ID=$(echo "$FLUSH_RESPONSE" | jq -r '.result[-1].update_id // empty')
-  if [[ -n "$LAST_UPDATE_ID" ]]; then
-    OFFSET=$((LAST_UPDATE_ID + 1))
-  else
-    OFFSET=0
-  fi
-
-  # Long-poll for a reply, collecting split messages over a 10s window
-  COLLECTED=""
-  DEADLINE=""
-
-  while true; do
-    if [[ -n "$DEADLINE" ]]; then
-      NOW=$(date +%s)
-      if [[ $NOW -ge $DEADLINE ]]; then
-        break
-      fi
-      POLL_TIMEOUT=2
-    else
-      POLL_TIMEOUT=30
-    fi
-
-    UPDATES=$(curl -s "${TELEGRAM_API}/getUpdates?offset=${OFFSET}&timeout=${POLL_TIMEOUT}")
-
-    MSG_COUNT=$(echo "$UPDATES" | jq --arg cid "$TELEGRAM_CHAT_ID" '
-      [.result[] | select(.message.chat.id == ($cid | tonumber) and .message.text != null)] | length
-    ')
-
-    if [[ "$MSG_COUNT" -gt 0 ]]; then
-      NEW_TEXTS=$(echo "$UPDATES" | jq -r --arg cid "$TELEGRAM_CHAT_ID" '
-        [.result[] | select(.message.chat.id == ($cid | tonumber) and .message.text != null)]
-        | .[].message.text
-      ')
-      if [[ -n "$COLLECTED" ]]; then
-        COLLECTED="${COLLECTED}
-${NEW_TEXTS}"
-      else
-        COLLECTED="$NEW_TEXTS"
-      fi
-
-      if [[ -z "$DEADLINE" ]]; then
-        DEADLINE=$(( $(date +%s) + 10 ))
-        echo "=== First message received, collecting for 10s... ===" >&2
-      fi
-    fi
-
-    NEW_LAST=$(echo "$UPDATES" | jq -r '.result[-1].update_id // empty')
-    if [[ -n "$NEW_LAST" ]]; then
-      OFFSET=$((NEW_LAST + 1))
-    fi
-  done
-
-  curl -s "${TELEGRAM_API}/getUpdates?offset=${OFFSET}" > /dev/null
-
-  echo "$COLLECTED" > "$ANSWER_FILE"
-  echo "=== Answer received from Telegram ===" >&2
-  echo "--- Begin answer ---" >&2
-  echo "$COLLECTED" >&2
-  echo "--- End answer ---" >&2
-
-  $LOOPX_BIN output --goto "apply-answer"
-  exit 0
-else
-  # No question — notify and loop back to copy-prompt
-  curl -s -X POST "${TELEGRAM_API}/sendMessage" \
-    -d chat_id="$TELEGRAM_CHAT_ID" \
-    -d text="Feedback applied. Ready for next review cycle." > /dev/null
-
-  rm -f "$CLAUDE_OUTPUT_FILE"
-  echo "=== No questions. Ready for next review cycle. ===" >&2
-  $LOOPX_BIN output --result "Feedback applied. Ready for next review cycle."
-fi
diff --git a/loopx-backup/review-adr/index.sh b/loopx-backup/review-adr/index.sh
deleted file mode 100755
index c75162d..0000000
--- a/loopx-backup/review-adr/index.sh
+++ /dev/null
@@ -1,58 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-ROOT="$LOOPX_PROJECT_ROOT"
-ADR_0001="$ROOT/adr/0001-adr-process.md"
-ADR_0004="$ROOT/adr/0004-tmpdir-and-args.md"
-SPEC="$ROOT/SPEC.md"
-PROMPT_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.prompt.tmp"
-
-if [[ ! -f "$ADR_0001" ]]; then
-  echo "Error: adr/0001-adr-process.md not found" >&2
-  exit 1
-fi
-
-if [[ ! -f "$ADR_0004" ]]; then
-  echo "Error: adr/0004-tmpdir-and-args.md not found" >&2
-  exit 1
-fi
-
-if [[ ! -f "$SPEC" ]]; then
-  echo "Error: SPEC.md not found" >&2
-  exit 1
-fi
-
-# Build the prompt and save to file (too long for a single Telegram message)
-cat <<PROMPT > "$PROMPT_FILE"
-Review ADR 0001, ADR 0004, and SPEC.md holistically and let me know if I can mark ADR 0004 as accepted or if I need to improve it further. Ask me clarifying questions if you have any doubts about my intentions for ADR 0004.
-
-adr/0001-adr-process.md:
-$(cat "$ADR_0001")
-
-adr/0004-tmpdir-and-args.md:
-$(cat "$ADR_0004")
-
-SPEC.md:
-$(cat "$SPEC")
-PROMPT
-
-MODE="${LOOPX_REVIEWER:-telegram}"
-case "$MODE" in
-  telegram)
-    exec ./lib/send-telegram.sh
-    ;;
-  codex)
-    exec ./lib/send-codex.sh
-    ;;
-  api)
-    if [[ ! -x ./node_modules/.bin/tsx ]]; then
-      echo "Error: ./node_modules/.bin/tsx not found. Run 'npm install' in $(pwd) to enable LOOPX_REVIEWER=api." >&2
-      exit 1
-    fi
-    exec ./node_modules/.bin/tsx ./lib/send-api.ts
-    ;;
-  *)
-    echo "Error: unknown LOOPX_REVIEWER='$MODE' (expected unset, 'telegram', 'codex', or 'api')" >&2
-    exit 1
-    ;;
-esac
diff --git a/loopx-backup/review-adr/lib/send-api.ts b/loopx-backup/review-adr/lib/send-api.ts
deleted file mode 100644
index ebdd380..0000000
--- a/loopx-backup/review-adr/lib/send-api.ts
+++ /dev/null
@@ -1,106 +0,0 @@
-import OpenAI, { toFile } from "openai";
-import { readFileSync, writeFileSync, rmSync, existsSync } from "node:fs";
-import { randomUUID } from "node:crypto";
-import { execFileSync } from "node:child_process";
-
-const ROOT = process.env.LOOPX_PROJECT_ROOT!;
-const WORKFLOW = process.env.LOOPX_WORKFLOW!;
-const BIN = process.env.LOOPX_BIN!;
-const THINKING = (process.env.GPT_PRO_THINKING ?? "medium") as
-  | "medium"
-  | "high"
-  | "xhigh";
-
-if (!process.env.OPENAI_API_KEY) {
-  console.error(
-    "OPENAI_API_KEY is required. Set via: loopx env set OPENAI_API_KEY <key>",
-  );
-  process.exit(1);
-}
-
-const PROMPT_FILE = `${ROOT}/.loopx/${WORKFLOW}/.prompt.tmp`;
-const FEEDBACK_FILE = `${ROOT}/.loopx/${WORKFLOW}/.feedback.tmp`;
-
-if (!existsSync(PROMPT_FILE)) {
-  console.error(`Error: prompt file not found at ${PROMPT_FILE}`);
-  process.exit(1);
-}
-
-const prompt = readFileSync(PROMPT_FILE, "utf8");
-
-if (existsSync(FEEDBACK_FILE)) rmSync(FEEDBACK_FILE);
-
-const client = new OpenAI();
-
-const batchLine = JSON.stringify({
-  custom_id: `gpt54-${randomUUID()}`,
-  method: "POST",
-  url: "/v1/responses",
-  body: {
-    model: "gpt-5.4-pro",
-    reasoning: { effort: THINKING },
-    input: prompt,
-  },
-});
-
-const inputFile = await client.files.create({
-  file: await toFile(
-    Buffer.from(batchLine + "\n", "utf8"),
-    `batch-${Date.now()}.jsonl`,
-    { type: "application/x-ndjson" },
-  ),
-  purpose: "batch",
-});
-
-const batch = await client.batches.create({
-  input_file_id: inputFile.id,
-  endpoint: "/v1/responses",
-  completion_window: "24h",
-});
-
-console.error(`submitted batch: ${batch.id}`);
-
-let b = batch;
-let lastStatus: string | undefined;
-while (
-  !b.output_file_id &&
-  !b.error_file_id &&
-  !["failed", "expired", "cancelled"].includes(b.status)
-) {
-  await new Promise((r) => setTimeout(r, 2000));
-  b = await client.batches.retrieve(batch.id);
-  if (b.status !== lastStatus) {
-    console.error(`waiting for batch ${b.id} (${b.status})...`);
-    lastStatus = b.status;
-  }
-}
-
-if (b.error_file_id) {
-  const err = await (await client.files.content(b.error_file_id)).text();
-  throw new Error(`Batch error: ${err}`);
-}
-if (!b.output_file_id) {
-  throw new Error(`Batch ${batch.id} ended in status ${b.status}`);
-}
-
-const outText = await (await client.files.content(b.output_file_id)).text();
-const line = JSON.parse(outText.trim().split(/\r?\n/)[0]);
-if (line.error) throw new Error(`Batch error: ${line.error.message}`);
-
-const resp = line.response.body as { output_text?: string; output?: any[] };
-const answer =
-  resp.output_text ??
-  (resp.output ?? [])
-    .filter((o: any) => o.type === "message")
-    .flatMap((o: any) => o.content ?? [])
-    .filter((c: any) => c.type === "output_text")
-    .map((c: any) => c.text)
-    .join("\n");
-
-writeFileSync(FEEDBACK_FILE, answer);
-rmSync(PROMPT_FILE);
-console.error("=== Feedback received from GPT-5.4-Pro ===");
-
-execFileSync(BIN, ["output", "--goto", "apply-feedback"], {
-  stdio: "inherit",
-});
diff --git a/loopx-backup/review-adr/lib/send-codex.sh b/loopx-backup/review-adr/lib/send-codex.sh
deleted file mode 100755
index 9f98df8..0000000
--- a/loopx-backup/review-adr/lib/send-codex.sh
+++ /dev/null
@@ -1,43 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-ROOT="$LOOPX_PROJECT_ROOT"
-PROMPT_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.prompt.tmp"
-FEEDBACK_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.feedback.tmp"
-
-if ! command -v codex >/dev/null 2>&1; then
-  echo "Error: codex CLI not found on PATH" >&2
-  exit 1
-fi
-
-if [[ ! -s "$PROMPT_FILE" ]]; then
-  echo "Error: prompt file not found at $PROMPT_FILE" >&2
-  exit 1
-fi
-
-echo "" >&2
-echo "=== Invoking codex CLI ===" >&2
-
-rm -f "$FEEDBACK_FILE"
-
-codex exec - \
-  --skip-git-repo-check \
-  --sandbox read-only \
-  --color never \
-  --output-last-message "$FEEDBACK_FILE" \
-  < "$PROMPT_FILE" >/dev/null
-
-rm -f "$PROMPT_FILE"
-
-if [[ ! -s "$FEEDBACK_FILE" ]]; then
-  echo "Error: codex produced no feedback" >&2
-  exit 1
-fi
-
-echo "=== Feedback received from codex ===" >&2
-echo "--- Begin feedback ---" >&2
-cat "$FEEDBACK_FILE" >&2
-echo "" >&2
-echo "--- End feedback ---" >&2
-
-$LOOPX_BIN output --goto "apply-feedback"
diff --git a/loopx-backup/review-adr/lib/send-telegram.sh b/loopx-backup/review-adr/lib/send-telegram.sh
deleted file mode 100755
index 9ecf963..0000000
--- a/loopx-backup/review-adr/lib/send-telegram.sh
+++ /dev/null
@@ -1,104 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-ROOT="$LOOPX_PROJECT_ROOT"
-PROMPT_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.prompt.tmp"
-FEEDBACK_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.feedback.tmp"
-
-: "${TELEGRAM_BOT_TOKEN:?TELEGRAM_BOT_TOKEN env var is required}"
-: "${TELEGRAM_CHAT_ID:?TELEGRAM_CHAT_ID env var is required}"
-
-if [[ ! -s "$PROMPT_FILE" ]]; then
-  echo "Error: prompt file not found at $PROMPT_FILE" >&2
-  exit 1
-fi
-
-TELEGRAM_API="https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}"
-
-# Flush old updates to get current offset
-FLUSH_RESPONSE=$(curl -s "${TELEGRAM_API}/getUpdates?offset=-1")
-LAST_UPDATE_ID=$(echo "$FLUSH_RESPONSE" | jq -r '.result[-1].update_id // empty')
-if [[ -n "$LAST_UPDATE_ID" ]]; then
-  OFFSET=$((LAST_UPDATE_ID + 1))
-else
-  OFFSET=0
-fi
-
-# Send the prompt as a document attachment
-SEND_RESPONSE=$(curl -s -X POST "${TELEGRAM_API}/sendDocument" \
-  -F chat_id="$TELEGRAM_CHAT_ID" \
-  -F document=@"$PROMPT_FILE;filename=review-prompt.md" \
-  -F caption="Review prompt — reply with your feedback")
-
-SENT_OK=$(echo "$SEND_RESPONSE" | jq -r '.ok')
-if [[ "$SENT_OK" != "true" ]]; then
-  echo "Error: Failed to send Telegram message: $SEND_RESPONSE" >&2
-  rm -f "$PROMPT_FILE"
-  exit 1
-fi
-
-rm -f "$PROMPT_FILE"
-
-echo "" >&2
-echo "=== Prompt sent to Telegram ===" >&2
-echo "Reply in the Telegram chat with your feedback." >&2
-echo "Waiting for reply..." >&2
-
-# Long-poll for a reply, collecting split messages over a 10s window
-COLLECTED=""
-DEADLINE=""
-
-while true; do
-  # After first message arrives, switch to short polls and enforce deadline
-  if [[ -n "$DEADLINE" ]]; then
-    NOW=$(date +%s)
-    if [[ $NOW -ge $DEADLINE ]]; then
-      break
-    fi
-    POLL_TIMEOUT=2
-  else
-    POLL_TIMEOUT=30
-  fi
-
-  UPDATES=$(curl -s "${TELEGRAM_API}/getUpdates?offset=${OFFSET}&timeout=${POLL_TIMEOUT}")
-
-  MSG_COUNT=$(echo "$UPDATES" | jq --arg cid "$TELEGRAM_CHAT_ID" '
-    [.result[] | select(.message.chat.id == ($cid | tonumber) and .message.text != null)] | length
-  ')
-
-  if [[ "$MSG_COUNT" -gt 0 ]]; then
-    NEW_TEXTS=$(echo "$UPDATES" | jq -r --arg cid "$TELEGRAM_CHAT_ID" '
-      [.result[] | select(.message.chat.id == ($cid | tonumber) and .message.text != null)]
-      | .[].message.text
-    ')
-    if [[ -n "$COLLECTED" ]]; then
-      COLLECTED="${COLLECTED}
-${NEW_TEXTS}"
-    else
-      COLLECTED="$NEW_TEXTS"
-    fi
-
-    # Start 10s collection window on first message
-    if [[ -z "$DEADLINE" ]]; then
-      DEADLINE=$(( $(date +%s) + 10 ))
-      echo "=== First message received, collecting for 10s... ===" >&2
-    fi
-  fi
-
-  # Advance offset past all updates
-  NEW_LAST=$(echo "$UPDATES" | jq -r '.result[-1].update_id // empty')
-  if [[ -n "$NEW_LAST" ]]; then
-    OFFSET=$((NEW_LAST + 1))
-  fi
-done
-
-# Acknowledge all collected updates
-curl -s "${TELEGRAM_API}/getUpdates?offset=${OFFSET}" > /dev/null
-
-echo "$COLLECTED" > "$FEEDBACK_FILE"
-echo "=== Feedback received from Telegram ===" >&2
-echo "--- Begin feedback ---" >&2
-echo "$COLLECTED" >&2
-echo "--- End feedback ---" >&2
-
-$LOOPX_BIN output --goto "apply-feedback"
diff --git a/loopx-backup/review-adr/package-lock.json b/loopx-backup/review-adr/package-lock.json
deleted file mode 100644
index def3045..0000000
--- a/loopx-backup/review-adr/package-lock.json
+++ /dev/null
@@ -1,545 +0,0 @@
-{
-  "name": "review-adr",
-  "lockfileVersion": 3,
-  "requires": true,
-  "packages": {
-    "": {
-      "dependencies": {
-        "openai": "^6.0.0",
-        "tsx": "^4.19.3"
-      }
-    },
-    "node_modules/@esbuild/aix-ppc64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.27.7.tgz",
-      "integrity": "sha512-EKX3Qwmhz1eMdEJokhALr0YiD0lhQNwDqkPYyPhiSwKrh7/4KRjQc04sZ8db+5DVVnZ1LmbNDI1uAMPEUBnQPg==",
-      "cpu": [
-        "ppc64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "aix"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@esbuild/android-arm": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.27.7.tgz",
-      "integrity": "sha512-jbPXvB4Yj2yBV7HUfE2KHe4GJX51QplCN1pGbYjvsyCZbQmies29EoJbkEc+vYuU5o45AfQn37vZlyXy4YJ8RQ==",
-      "cpu": [
-        "arm"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "android"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@esbuild/android-arm64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.27.7.tgz",
-      "integrity": "sha512-62dPZHpIXzvChfvfLJow3q5dDtiNMkwiRzPylSCfriLvZeq0a1bWChrGx/BbUbPwOrsWKMn8idSllklzBy+dgQ==",
-      "cpu": [
-        "arm64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "android"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@esbuild/android-x64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.27.7.tgz",
-      "integrity": "sha512-x5VpMODneVDb70PYV2VQOmIUUiBtY3D3mPBG8NxVk5CogneYhkR7MmM3yR/uMdITLrC1ml/NV1rj4bMJuy9MCg==",
-      "cpu": [
-        "x64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "android"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@esbuild/darwin-arm64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.27.7.tgz",
-      "integrity": "sha512-5lckdqeuBPlKUwvoCXIgI2D9/ABmPq3Rdp7IfL70393YgaASt7tbju3Ac+ePVi3KDH6N2RqePfHnXkaDtY9fkw==",
-      "cpu": [
-        "arm64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "darwin"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@esbuild/darwin-x64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.27.7.tgz",
-      "integrity": "sha512-rYnXrKcXuT7Z+WL5K980jVFdvVKhCHhUwid+dDYQpH+qu+TefcomiMAJpIiC2EM3Rjtq0sO3StMV/+3w3MyyqQ==",
-      "cpu": [
-        "x64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "darwin"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@esbuild/freebsd-arm64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.27.7.tgz",
-      "integrity": "sha512-B48PqeCsEgOtzME2GbNM2roU29AMTuOIN91dsMO30t+Ydis3z/3Ngoj5hhnsOSSwNzS+6JppqWsuhTp6E82l2w==",
-      "cpu": [
-        "arm64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "freebsd"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@esbuild/freebsd-x64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.27.7.tgz",
-      "integrity": "sha512-jOBDK5XEjA4m5IJK3bpAQF9/Lelu/Z9ZcdhTRLf4cajlB+8VEhFFRjWgfy3M1O4rO2GQ/b2dLwCUGpiF/eATNQ==",
-      "cpu": [
-        "x64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "freebsd"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@esbuild/linux-arm": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.27.7.tgz",
-      "integrity": "sha512-RkT/YXYBTSULo3+af8Ib0ykH8u2MBh57o7q/DAs3lTJlyVQkgQvlrPTnjIzzRPQyavxtPtfg0EopvDyIt0j1rA==",
-      "cpu": [
-        "arm"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@esbuild/linux-arm64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.27.7.tgz",
-      "integrity": "sha512-RZPHBoxXuNnPQO9rvjh5jdkRmVizktkT7TCDkDmQ0W2SwHInKCAV95GRuvdSvA7w4VMwfCjUiPwDi0ZO6Nfe9A==",
-      "cpu": [
-        "arm64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@esbuild/linux-ia32": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.27.7.tgz",
-      "integrity": "sha512-GA48aKNkyQDbd3KtkplYWT102C5sn/EZTY4XROkxONgruHPU72l+gW+FfF8tf2cFjeHaRbWpOYa/uRBz/Xq1Pg==",
-      "cpu": [
-        "ia32"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@esbuild/linux-loong64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.27.7.tgz",
-      "integrity": "sha512-a4POruNM2oWsD4WKvBSEKGIiWQF8fZOAsycHOt6JBpZ+JN2n2JH9WAv56SOyu9X5IqAjqSIPTaJkqN8F7XOQ5Q==",
-      "cpu": [
-        "loong64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@esbuild/linux-mips64el": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.27.7.tgz",
-      "integrity": "sha512-KabT5I6StirGfIz0FMgl1I+R1H73Gp0ofL9A3nG3i/cYFJzKHhouBV5VWK1CSgKvVaG4q1RNpCTR2LuTVB3fIw==",
-      "cpu": [
-        "mips64el"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@esbuild/linux-ppc64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.27.7.tgz",
-      "integrity": "sha512-gRsL4x6wsGHGRqhtI+ifpN/vpOFTQtnbsupUF5R5YTAg+y/lKelYR1hXbnBdzDjGbMYjVJLJTd2OFmMewAgwlQ==",
-      "cpu": [
-        "ppc64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@esbuild/linux-riscv64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.27.7.tgz",
-      "integrity": "sha512-hL25LbxO1QOngGzu2U5xeXtxXcW+/GvMN3ejANqXkxZ/opySAZMrc+9LY/WyjAan41unrR3YrmtTsUpwT66InQ==",
-      "cpu": [
-        "riscv64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@esbuild/linux-s390x": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.27.7.tgz",
-      "integrity": "sha512-2k8go8Ycu1Kb46vEelhu1vqEP+UeRVj2zY1pSuPdgvbd5ykAw82Lrro28vXUrRmzEsUV0NzCf54yARIK8r0fdw==",
-      "cpu": [
-        "s390x"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@esbuild/linux-x64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.27.7.tgz",
-      "integrity": "sha512-hzznmADPt+OmsYzw1EE33ccA+HPdIqiCRq7cQeL1Jlq2gb1+OyWBkMCrYGBJ+sxVzve2ZJEVeePbLM2iEIZSxA==",
-      "cpu": [
-        "x64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@esbuild/netbsd-arm64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.27.7.tgz",
-      "integrity": "sha512-b6pqtrQdigZBwZxAn1UpazEisvwaIDvdbMbmrly7cDTMFnw/+3lVxxCTGOrkPVnsYIosJJXAsILG9XcQS+Yu6w==",
-      "cpu": [
-        "arm64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "netbsd"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@esbuild/netbsd-x64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.27.7.tgz",
-      "integrity": "sha512-OfatkLojr6U+WN5EDYuoQhtM+1xco+/6FSzJJnuWiUw5eVcicbyK3dq5EeV/QHT1uy6GoDhGbFpprUiHUYggrw==",
-      "cpu": [
-        "x64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "netbsd"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@esbuild/openbsd-arm64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.27.7.tgz",
-      "integrity": "sha512-AFuojMQTxAz75Fo8idVcqoQWEHIXFRbOc1TrVcFSgCZtQfSdc1RXgB3tjOn/krRHENUB4j00bfGjyl2mJrU37A==",
-      "cpu": [
-        "arm64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "openbsd"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@esbuild/openbsd-x64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.27.7.tgz",
-      "integrity": "sha512-+A1NJmfM8WNDv5CLVQYJ5PshuRm/4cI6WMZRg1by1GwPIQPCTs1GLEUHwiiQGT5zDdyLiRM/l1G0Pv54gvtKIg==",
-      "cpu": [
-        "x64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "openbsd"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@esbuild/openharmony-arm64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.27.7.tgz",
-      "integrity": "sha512-+KrvYb/C8zA9CU/g0sR6w2RBw7IGc5J2BPnc3dYc5VJxHCSF1yNMxTV5LQ7GuKteQXZtspjFbiuW5/dOj7H4Yw==",
-      "cpu": [
-        "arm64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "openharmony"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@esbuild/sunos-x64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.27.7.tgz",
-      "integrity": "sha512-ikktIhFBzQNt/QDyOL580ti9+5mL/YZeUPKU2ivGtGjdTYoqz6jObj6nOMfhASpS4GU4Q/Clh1QtxWAvcYKamA==",
-      "cpu": [
-        "x64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "sunos"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@esbuild/win32-arm64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.27.7.tgz",
-      "integrity": "sha512-7yRhbHvPqSpRUV7Q20VuDwbjW5kIMwTHpptuUzV+AA46kiPze5Z7qgt6CLCK3pWFrHeNfDd1VKgyP4O+ng17CA==",
-      "cpu": [
-        "arm64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "win32"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@esbuild/win32-ia32": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.27.7.tgz",
-      "integrity": "sha512-SmwKXe6VHIyZYbBLJrhOoCJRB/Z1tckzmgTLfFYOfpMAx63BJEaL9ExI8x7v0oAO3Zh6D/Oi1gVxEYr5oUCFhw==",
-      "cpu": [
-        "ia32"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "win32"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@esbuild/win32-x64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.27.7.tgz",
-      "integrity": "sha512-56hiAJPhwQ1R4i+21FVF7V8kSD5zZTdHcVuRFMW0hn753vVfQN8xlx4uOPT4xoGH0Z/oVATuR82AiqSTDIpaHg==",
-      "cpu": [
-        "x64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "win32"
-      ],
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/esbuild": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.27.7.tgz",
-      "integrity": "sha512-IxpibTjyVnmrIQo5aqNpCgoACA/dTKLTlhMHihVHhdkxKyPO1uBBthumT0rdHmcsk9uMonIWS0m4FljWzILh3w==",
-      "hasInstallScript": true,
-      "license": "MIT",
-      "bin": {
-        "esbuild": "bin/esbuild"
-      },
-      "engines": {
-        "node": ">=18"
-      },
-      "optionalDependencies": {
-        "@esbuild/aix-ppc64": "0.27.7",
-        "@esbuild/android-arm": "0.27.7",
-        "@esbuild/android-arm64": "0.27.7",
-        "@esbuild/android-x64": "0.27.7",
-        "@esbuild/darwin-arm64": "0.27.7",
-        "@esbuild/darwin-x64": "0.27.7",
-        "@esbuild/freebsd-arm64": "0.27.7",
-        "@esbuild/freebsd-x64": "0.27.7",
-        "@esbuild/linux-arm": "0.27.7",
-        "@esbuild/linux-arm64": "0.27.7",
-        "@esbuild/linux-ia32": "0.27.7",
-        "@esbuild/linux-loong64": "0.27.7",
-        "@esbuild/linux-mips64el": "0.27.7",
-        "@esbuild/linux-ppc64": "0.27.7",
-        "@esbuild/linux-riscv64": "0.27.7",
-        "@esbuild/linux-s390x": "0.27.7",
-        "@esbuild/linux-x64": "0.27.7",
-        "@esbuild/netbsd-arm64": "0.27.7",
-        "@esbuild/netbsd-x64": "0.27.7",
-        "@esbuild/openbsd-arm64": "0.27.7",
-        "@esbuild/openbsd-x64": "0.27.7",
-        "@esbuild/openharmony-arm64": "0.27.7",
-        "@esbuild/sunos-x64": "0.27.7",
-        "@esbuild/win32-arm64": "0.27.7",
-        "@esbuild/win32-ia32": "0.27.7",
-        "@esbuild/win32-x64": "0.27.7"
-      }
-    },
-    "node_modules/fsevents": {
-      "version": "2.3.3",
-      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
-      "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
-      "hasInstallScript": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "darwin"
-      ],
-      "engines": {
-        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
-      }
-    },
-    "node_modules/get-tsconfig": {
-      "version": "4.14.0",
-      "resolved": "https://registry.npmjs.org/get-tsconfig/-/get-tsconfig-4.14.0.tgz",
-      "integrity": "sha512-yTb+8DXzDREzgvYmh6s9vHsSVCHeC0G3PI5bEXNBHtmshPnO+S5O7qgLEOn0I5QvMy6kpZN8K1NKGyilLb93wA==",
-      "license": "MIT",
-      "dependencies": {
-        "resolve-pkg-maps": "^1.0.0"
-      },
-      "funding": {
-        "url": "https://github.com/privatenumber/get-tsconfig?sponsor=1"
-      }
-    },
-    "node_modules/openai": {
-      "version": "6.34.0",
-      "resolved": "https://registry.npmjs.org/openai/-/openai-6.34.0.tgz",
-      "integrity": "sha512-yEr2jdGf4tVFYG6ohmr3pF6VJuveP0EA/sS8TBx+4Eq5NT10alu5zg2dmxMXMgqpihRDQlFGpRt2XwsGj+Fyxw==",
-      "license": "Apache-2.0",
-      "bin": {
-        "openai": "bin/cli"
-      },
-      "peerDependencies": {
-        "ws": "^8.18.0",
-        "zod": "^3.25 || ^4.0"
-      },
-      "peerDependenciesMeta": {
-        "ws": {
-          "optional": true
-        },
-        "zod": {
-          "optional": true
-        }
-      }
-    },
-    "node_modules/resolve-pkg-maps": {
-      "version": "1.0.0",
-      "resolved": "https://registry.npmjs.org/resolve-pkg-maps/-/resolve-pkg-maps-1.0.0.tgz",
-      "integrity": "sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==",
-      "license": "MIT",
-      "funding": {
-        "url": "https://github.com/privatenumber/resolve-pkg-maps?sponsor=1"
-      }
-    },
-    "node_modules/tsx": {
-      "version": "4.21.0",
-      "resolved": "https://registry.npmjs.org/tsx/-/tsx-4.21.0.tgz",
-      "integrity": "sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw==",
-      "license": "MIT",
-      "dependencies": {
-        "esbuild": "~0.27.0",
-        "get-tsconfig": "^4.7.5"
-      },
-      "bin": {
-        "tsx": "dist/cli.mjs"
-      },
-      "engines": {
-        "node": ">=18.0.0"
-      },
-      "optionalDependencies": {
-        "fsevents": "~2.3.3"
-      }
-    }
-  }
-}
diff --git a/loopx-backup/review-adr/package.json b/loopx-backup/review-adr/package.json
deleted file mode 100644
index 025b36b..0000000
--- a/loopx-backup/review-adr/package.json
+++ /dev/null
@@ -1,7 +0,0 @@
-{
-  "type": "module",
-  "dependencies": {
-    "openai": "^6.0.0",
-    "tsx": "^4.19.3"
-  }
-}
diff --git a/loopx-backup/spec-test-adr/apply-answer.sh b/loopx-backup/spec-test-adr/apply-answer.sh
deleted file mode 100755
index d406614..0000000
--- a/loopx-backup/spec-test-adr/apply-answer.sh
+++ /dev/null
@@ -1,23 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-ROOT="$LOOPX_PROJECT_ROOT"
-CLAUDE_OUTPUT_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.claude-output.tmp"
-ANSWER_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.answer.tmp"
-
-if [[ ! -f "$ANSWER_FILE" ]]; then
-  echo "Error: No answer file found at $ANSWER_FILE" >&2
-  exit 1
-fi
-
-ANSWER=$(cat "$ANSWER_FILE")
-
-# Continue the existing conversation started by apply-feedback
-CLAUDE_OUTPUT=$(echo "$ANSWER" | claude --dangerously-skip-permissions -c -p 2>/dev/null)
-
-echo "$CLAUDE_OUTPUT" > "$CLAUDE_OUTPUT_FILE"
-rm -f "$ANSWER_FILE"
-
-echo "=== Claude processed the answer ===" >&2
-
-$LOOPX_BIN output --goto "check-question"
diff --git a/loopx-backup/spec-test-adr/apply-feedback.sh b/loopx-backup/spec-test-adr/apply-feedback.sh
deleted file mode 100755
index 0c9071f..0000000
--- a/loopx-backup/spec-test-adr/apply-feedback.sh
+++ /dev/null
@@ -1,28 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-ROOT="$LOOPX_PROJECT_ROOT"
-FEEDBACK_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.feedback.tmp"
-CLAUDE_OUTPUT_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.claude-output.tmp"
-
-if [[ ! -f "$FEEDBACK_FILE" ]]; then
-  echo "Error: No feedback file found at $FEEDBACK_FILE" >&2
-  exit 1
-fi
-
-FEEDBACK=$(cat "$FEEDBACK_FILE")
-
-PROMPT="ADR-0002 has been accepted and SPEC.md has already been updated to incorporate its changes (per the ADR process in ADR-0001). I am now updating TEST-SPEC.md to cover the new and changed spec behavior introduced by ADR-0002. I received the following feedback on the current state of TEST-SPEC.md. Read adr/0002-run-subcommand.md (accepted — read-only reference), SPEC.md (already updated for ADR-0002 — read-only reference), and TEST-SPEC.md (target of updates) yourself before acting. Apply this feedback by updating TEST-SPEC.md only — do not modify SPEC.md or ADR-0002, they are read-only references in this cycle. ADR-0002 and the updated SPEC.md are the authoritative sources for what TEST-SPEC.md should cover. If there is any ambiguity about my intentions, ask me clarifying questions. Think critically about this feedback and push back if warranted. After you finish, commit and push.
-
-Feedback:
-$FEEDBACK"
-
-CLAUDE_OUTPUT=$(echo "$PROMPT" | claude --dangerously-skip-permissions -p 2>/dev/null)
-
-rm -f "$FEEDBACK_FILE"
-echo "$CLAUDE_OUTPUT" > "$CLAUDE_OUTPUT_FILE"
-
-echo "" >&2
-echo "=== Claude finished applying feedback ===" >&2
-
-$LOOPX_BIN output --goto "check-question"
diff --git a/loopx-backup/spec-test-adr/check-question.schema.json b/loopx-backup/spec-test-adr/check-question.schema.json
deleted file mode 100644
index fe39a58..0000000
--- a/loopx-backup/spec-test-adr/check-question.schema.json
+++ /dev/null
@@ -1,11 +0,0 @@
-{
-  "type": "object",
-  "properties": {
-    "has_question": {
-      "description": "true if the text contains a question or request for clarification directed at the user, false otherwise",
-      "type": "boolean"
-    }
-  },
-  "required": ["has_question"],
-  "additionalProperties": false
-}
diff --git a/loopx-backup/spec-test-adr/check-question.sh b/loopx-backup/spec-test-adr/check-question.sh
deleted file mode 100755
index 45d4306..0000000
--- a/loopx-backup/spec-test-adr/check-question.sh
+++ /dev/null
@@ -1,121 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-ROOT="$LOOPX_PROJECT_ROOT"
-CLAUDE_OUTPUT_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.claude-output.tmp"
-ANSWER_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.answer.tmp"
-
-: "${TELEGRAM_BOT_TOKEN:?TELEGRAM_BOT_TOKEN env var is required}"
-: "${TELEGRAM_CHAT_ID:?TELEGRAM_CHAT_ID env var is required}"
-
-TELEGRAM_API="https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}"
-
-if [[ ! -f "$CLAUDE_OUTPUT_FILE" ]]; then
-  echo "Error: No Claude output file found at $CLAUDE_OUTPUT_FILE" >&2
-  exit 1
-fi
-
-CLAUDE_OUTPUT=$(cat "$CLAUDE_OUTPUT_FILE")
-
-# Use Codex with output schema to deterministically classify the output
-SCHEMA="$ROOT/.loopx/$LOOPX_WORKFLOW/check-question.schema.json"
-VERDICT=$(codex exec --output-schema "$SCHEMA" "Does the following text contain a question or request for clarification directed at the user?
-
-$CLAUDE_OUTPUT" 2>/dev/null)
-
-HAS_QUESTION=$(echo "$VERDICT" | jq -r '.has_question')
-
-if [[ "$HAS_QUESTION" == "true" ]]; then
-  echo "=== Claude has a question — sending to Telegram ===" >&2
-
-  # Send as document if too long for a message, otherwise as text
-  if [[ ${#CLAUDE_OUTPUT} -gt 4000 ]]; then
-    QUESTION_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.question.tmp"
-    echo "$CLAUDE_OUTPUT" > "$QUESTION_FILE"
-    curl -s -X POST "${TELEGRAM_API}/sendDocument" \
-      -F chat_id="$TELEGRAM_CHAT_ID" \
-      -F document=@"$QUESTION_FILE;filename=question.md" \
-      -F caption="Claude has a question — reply with your answer" > /dev/null
-    rm -f "$QUESTION_FILE"
-  else
-    curl -s -X POST "${TELEGRAM_API}/sendMessage" \
-      -d chat_id="$TELEGRAM_CHAT_ID" \
-      --data-urlencode "text=${CLAUDE_OUTPUT}" > /dev/null
-  fi
-
-  echo "Waiting for answer..." >&2
-
-  # Flush old updates to get current offset
-  FLUSH_RESPONSE=$(curl -s "${TELEGRAM_API}/getUpdates?offset=-1")
-  LAST_UPDATE_ID=$(echo "$FLUSH_RESPONSE" | jq -r '.result[-1].update_id // empty')
-  if [[ -n "$LAST_UPDATE_ID" ]]; then
-    OFFSET=$((LAST_UPDATE_ID + 1))
-  else
-    OFFSET=0
-  fi
-
-  # Long-poll for a reply, collecting split messages over a 10s window
-  COLLECTED=""
-  DEADLINE=""
-
-  while true; do
-    if [[ -n "$DEADLINE" ]]; then
-      NOW=$(date +%s)
-      if [[ $NOW -ge $DEADLINE ]]; then
-        break
-      fi
-      POLL_TIMEOUT=2
-    else
-      POLL_TIMEOUT=30
-    fi
-
-    UPDATES=$(curl -s "${TELEGRAM_API}/getUpdates?offset=${OFFSET}&timeout=${POLL_TIMEOUT}")
-
-    MSG_COUNT=$(echo "$UPDATES" | jq --arg cid "$TELEGRAM_CHAT_ID" '
-      [.result[] | select(.message.chat.id == ($cid | tonumber) and .message.text != null)] | length
-    ')
-
-    if [[ "$MSG_COUNT" -gt 0 ]]; then
-      NEW_TEXTS=$(echo "$UPDATES" | jq -r --arg cid "$TELEGRAM_CHAT_ID" '
-        [.result[] | select(.message.chat.id == ($cid | tonumber) and .message.text != null)]
-        | .[].message.text
-      ')
-      if [[ -n "$COLLECTED" ]]; then
-        COLLECTED="${COLLECTED}
-${NEW_TEXTS}"
-      else
-        COLLECTED="$NEW_TEXTS"
-      fi
-
-      if [[ -z "$DEADLINE" ]]; then
-        DEADLINE=$(( $(date +%s) + 10 ))
-        echo "=== First message received, collecting for 10s... ===" >&2
-      fi
-    fi
-
-    NEW_LAST=$(echo "$UPDATES" | jq -r '.result[-1].update_id // empty')
-    if [[ -n "$NEW_LAST" ]]; then
-      OFFSET=$((NEW_LAST + 1))
-    fi
-  done
-
-  curl -s "${TELEGRAM_API}/getUpdates?offset=${OFFSET}" > /dev/null
-
-  echo "$COLLECTED" > "$ANSWER_FILE"
-  echo "=== Answer received from Telegram ===" >&2
-  echo "--- Begin answer ---" >&2
-  echo "$COLLECTED" >&2
-  echo "--- End answer ---" >&2
-
-  $LOOPX_BIN output --goto "apply-answer"
-  exit 0
-else
-  # No question — notify and loop back to copy-prompt
-  curl -s -X POST "${TELEGRAM_API}/sendMessage" \
-    -d chat_id="$TELEGRAM_CHAT_ID" \
-    -d text="Feedback applied. Ready for next review cycle." > /dev/null
-
-  rm -f "$CLAUDE_OUTPUT_FILE"
-  echo "=== No questions. Ready for next review cycle. ===" >&2
-  $LOOPX_BIN output --result "Feedback applied. Ready for next review cycle."
-fi
diff --git a/loopx-backup/spec-test-adr/index.sh b/loopx-backup/spec-test-adr/index.sh
deleted file mode 100755
index 7e646e7..0000000
--- a/loopx-backup/spec-test-adr/index.sh
+++ /dev/null
@@ -1,66 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-ROOT="$LOOPX_PROJECT_ROOT"
-ADR_0001="$ROOT/adr/0001-adr-process.md"
-ADR_0002="$ROOT/adr/0002-run-subcommand.md"
-SPEC="$ROOT/SPEC.md"
-TEST_SPEC="$ROOT/TEST-SPEC.md"
-PROMPT_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.prompt.tmp"
-
-if [[ ! -f "$ADR_0001" ]]; then
-  echo "Error: adr/0001-adr-process.md not found" >&2
-  exit 1
-fi
-
-if [[ ! -f "$ADR_0002" ]]; then
-  echo "Error: adr/0002-run-subcommand.md not found" >&2
-  exit 1
-fi
-
-if [[ ! -f "$SPEC" ]]; then
-  echo "Error: SPEC.md not found" >&2
-  exit 1
-fi
-
-if [[ ! -f "$TEST_SPEC" ]]; then
-  echo "Error: TEST-SPEC.md not found" >&2
-  exit 1
-fi
-
-# Build the prompt and save to file (too long for a single Telegram message)
-cat <<PROMPT > "$PROMPT_FILE"
-ADR 0002 has been accepted and SPEC.md has already been updated to incorporate its changes (ADR status: "Spec Updated"). Per the ADR process in ADR-0001, the next step is to update TEST-SPEC.md to cover the new and changed spec behavior introduced by ADR-0002. In this cycle, TEST-SPEC.md is the only file that should be modified — SPEC.md and ADR-0002 are read-only references.
-
-Review the current TEST-SPEC.md against the updated SPEC.md and ADR-0002, and let me know whether TEST-SPEC.md already covers the ADR-0002 changes correctly and completely, or what needs to be added, changed, or removed. Do not suggest changes to SPEC.md or ADR-0002 — if something looks wrong in those, flag it but do not act on it.
-
-adr/0002-run-subcommand.md (accepted — read-only reference):
-$(cat "$ADR_0002")
-
-SPEC.md (already updated for ADR-0002 — read-only reference):
-$(cat "$SPEC")
-
-TEST-SPEC.md (target of updates):
-$(cat "$TEST_SPEC")
-PROMPT
-
-MODE="${LOOPX_REVIEWER:-telegram}"
-case "$MODE" in
-  telegram)
-    exec ./lib/send-telegram.sh
-    ;;
-  codex)
-    exec ./lib/send-codex.sh
-    ;;
-  api)
-    if [[ ! -x ./node_modules/.bin/tsx ]]; then
-      echo "Error: ./node_modules/.bin/tsx not found. Run 'npm install' in $(pwd) to enable LOOPX_REVIEWER=api." >&2
-      exit 1
-    fi
-    exec ./node_modules/.bin/tsx ./lib/send-api.ts
-    ;;
-  *)
-    echo "Error: unknown LOOPX_REVIEWER='$MODE' (expected unset, 'telegram', 'codex', or 'api')" >&2
-    exit 1
-    ;;
-esac
diff --git a/loopx-backup/spec-test-adr/lib/send-api.ts b/loopx-backup/spec-test-adr/lib/send-api.ts
deleted file mode 100644
index ebdd380..0000000
--- a/loopx-backup/spec-test-adr/lib/send-api.ts
+++ /dev/null
@@ -1,106 +0,0 @@
-import OpenAI, { toFile } from "openai";
-import { readFileSync, writeFileSync, rmSync, existsSync } from "node:fs";
-import { randomUUID } from "node:crypto";
-import { execFileSync } from "node:child_process";
-
-const ROOT = process.env.LOOPX_PROJECT_ROOT!;
-const WORKFLOW = process.env.LOOPX_WORKFLOW!;
-const BIN = process.env.LOOPX_BIN!;
-const THINKING = (process.env.GPT_PRO_THINKING ?? "medium") as
-  | "medium"
-  | "high"
-  | "xhigh";
-
-if (!process.env.OPENAI_API_KEY) {
-  console.error(
-    "OPENAI_API_KEY is required. Set via: loopx env set OPENAI_API_KEY <key>",
-  );
-  process.exit(1);
-}
-
-const PROMPT_FILE = `${ROOT}/.loopx/${WORKFLOW}/.prompt.tmp`;
-const FEEDBACK_FILE = `${ROOT}/.loopx/${WORKFLOW}/.feedback.tmp`;
-
-if (!existsSync(PROMPT_FILE)) {
-  console.error(`Error: prompt file not found at ${PROMPT_FILE}`);
-  process.exit(1);
-}
-
-const prompt = readFileSync(PROMPT_FILE, "utf8");
-
-if (existsSync(FEEDBACK_FILE)) rmSync(FEEDBACK_FILE);
-
-const client = new OpenAI();
-
-const batchLine = JSON.stringify({
-  custom_id: `gpt54-${randomUUID()}`,
-  method: "POST",
-  url: "/v1/responses",
-  body: {
-    model: "gpt-5.4-pro",
-    reasoning: { effort: THINKING },
-    input: prompt,
-  },
-});
-
-const inputFile = await client.files.create({
-  file: await toFile(
-    Buffer.from(batchLine + "\n", "utf8"),
-    `batch-${Date.now()}.jsonl`,
-    { type: "application/x-ndjson" },
-  ),
-  purpose: "batch",
-});
-
-const batch = await client.batches.create({
-  input_file_id: inputFile.id,
-  endpoint: "/v1/responses",
-  completion_window: "24h",
-});
-
-console.error(`submitted batch: ${batch.id}`);
-
-let b = batch;
-let lastStatus: string | undefined;
-while (
-  !b.output_file_id &&
-  !b.error_file_id &&
-  !["failed", "expired", "cancelled"].includes(b.status)
-) {
-  await new Promise((r) => setTimeout(r, 2000));
-  b = await client.batches.retrieve(batch.id);
-  if (b.status !== lastStatus) {
-    console.error(`waiting for batch ${b.id} (${b.status})...`);
-    lastStatus = b.status;
-  }
-}
-
-if (b.error_file_id) {
-  const err = await (await client.files.content(b.error_file_id)).text();
-  throw new Error(`Batch error: ${err}`);
-}
-if (!b.output_file_id) {
-  throw new Error(`Batch ${batch.id} ended in status ${b.status}`);
-}
-
-const outText = await (await client.files.content(b.output_file_id)).text();
-const line = JSON.parse(outText.trim().split(/\r?\n/)[0]);
-if (line.error) throw new Error(`Batch error: ${line.error.message}`);
-
-const resp = line.response.body as { output_text?: string; output?: any[] };
-const answer =
-  resp.output_text ??
-  (resp.output ?? [])
-    .filter((o: any) => o.type === "message")
-    .flatMap((o: any) => o.content ?? [])
-    .filter((c: any) => c.type === "output_text")
-    .map((c: any) => c.text)
-    .join("\n");
-
-writeFileSync(FEEDBACK_FILE, answer);
-rmSync(PROMPT_FILE);
-console.error("=== Feedback received from GPT-5.4-Pro ===");
-
-execFileSync(BIN, ["output", "--goto", "apply-feedback"], {
-  stdio: "inherit",
-});
diff --git a/loopx-backup/spec-test-adr/lib/send-codex.sh b/loopx-backup/spec-test-adr/lib/send-codex.sh
deleted file mode 100755
index 9f98df8..0000000
--- a/loopx-backup/spec-test-adr/lib/send-codex.sh
+++ /dev/null
@@ -1,43 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-ROOT="$LOOPX_PROJECT_ROOT"
-PROMPT_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.prompt.tmp"
-FEEDBACK_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.feedback.tmp"
-
-if ! command -v codex >/dev/null 2>&1; then
-  echo "Error: codex CLI not found on PATH" >&2
-  exit 1
-fi
-
-if [[ ! -s "$PROMPT_FILE" ]]; then
-  echo "Error: prompt file not found at $PROMPT_FILE" >&2
-  exit 1
-fi
-
-echo "" >&2
-echo "=== Invoking codex CLI ===" >&2
-
-rm -f "$FEEDBACK_FILE"
-
-codex exec - \
-  --skip-git-repo-check \
-  --sandbox read-only \
-  --color never \
-  --output-last-message "$FEEDBACK_FILE" \
-  < "$PROMPT_FILE" >/dev/null
-
-rm -f "$PROMPT_FILE"
-
-if [[ ! -s "$FEEDBACK_FILE" ]]; then
-  echo "Error: codex produced no feedback" >&2
-  exit 1
-fi
-
-echo "=== Feedback received from codex ===" >&2
-echo "--- Begin feedback ---" >&2
-cat "$FEEDBACK_FILE" >&2
-echo "" >&2
-echo "--- End feedback ---" >&2
-
-$LOOPX_BIN output --goto "apply-feedback"
diff --git a/loopx-backup/spec-test-adr/lib/send-telegram.sh b/loopx-backup/spec-test-adr/lib/send-telegram.sh
deleted file mode 100755
index 9ecf963..0000000
--- a/loopx-backup/spec-test-adr/lib/send-telegram.sh
+++ /dev/null
@@ -1,104 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-ROOT="$LOOPX_PROJECT_ROOT"
-PROMPT_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.prompt.tmp"
-FEEDBACK_FILE="$ROOT/.loopx/$LOOPX_WORKFLOW/.feedback.tmp"
-
-: "${TELEGRAM_BOT_TOKEN:?TELEGRAM_BOT_TOKEN env var is required}"
-: "${TELEGRAM_CHAT_ID:?TELEGRAM_CHAT_ID env var is required}"
-
-if [[ ! -s "$PROMPT_FILE" ]]; then
-  echo "Error: prompt file not found at $PROMPT_FILE" >&2
-  exit 1
-fi
-
-TELEGRAM_API="https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}"
-
-# Flush old updates to get current offset
-FLUSH_RESPONSE=$(curl -s "${TELEGRAM_API}/getUpdates?offset=-1")
-LAST_UPDATE_ID=$(echo "$FLUSH_RESPONSE" | jq -r '.result[-1].update_id // empty')
-if [[ -n "$LAST_UPDATE_ID" ]]; then
-  OFFSET=$((LAST_UPDATE_ID + 1))
-else
-  OFFSET=0
-fi
-
-# Send the prompt as a document attachment
-SEND_RESPONSE=$(curl -s -X POST "${TELEGRAM_API}/sendDocument" \
-  -F chat_id="$TELEGRAM_CHAT_ID" \
-  -F document=@"$PROMPT_FILE;filename=review-prompt.md" \
-  -F caption="Review prompt — reply with your feedback")
-
-SENT_OK=$(echo "$SEND_RESPONSE" | jq -r '.ok')
-if [[ "$SENT_OK" != "true" ]]; then
-  echo "Error: Failed to send Telegram message: $SEND_RESPONSE" >&2
-  rm -f "$PROMPT_FILE"
-  exit 1
-fi
-
-rm -f "$PROMPT_FILE"
-
-echo "" >&2
-echo "=== Prompt sent to Telegram ===" >&2
-echo "Reply in the Telegram chat with your feedback." >&2
-echo "Waiting for reply..." >&2
-
-# Long-poll for a reply, collecting split messages over a 10s window
-COLLECTED=""
-DEADLINE=""
-
-while true; do
-  # After first message arrives, switch to short polls and enforce deadline
-  if [[ -n "$DEADLINE" ]]; then
-    NOW=$(date +%s)
-    if [[ $NOW -ge $DEADLINE ]]; then
-      break
-    fi
-    POLL_TIMEOUT=2
-  else
-    POLL_TIMEOUT=30
-  fi
-
-  UPDATES=$(curl -s "${TELEGRAM_API}/getUpdates?offset=${OFFSET}&timeout=${POLL_TIMEOUT}")
-
-  MSG_COUNT=$(echo "$UPDATES" | jq --arg cid "$TELEGRAM_CHAT_ID" '
-    [.result[] | select(.message.chat.id == ($cid | tonumber) and .message.text != null)] | length
-  ')
-
-  if [[ "$MSG_COUNT" -gt 0 ]]; then
-    NEW_TEXTS=$(echo "$UPDATES" | jq -r --arg cid "$TELEGRAM_CHAT_ID" '
-      [.result[] | select(.message.chat.id == ($cid | tonumber) and .message.text != null)]
-      | .[].message.text
-    ')
-    if [[ -n "$COLLECTED" ]]; then
-      COLLECTED="${COLLECTED}
-${NEW_TEXTS}"
-    else
-      COLLECTED="$NEW_TEXTS"
-    fi
-
-    # Start 10s collection window on first message
-    if [[ -z "$DEADLINE" ]]; then
-      DEADLINE=$(( $(date +%s) + 10 ))
-      echo "=== First message received, collecting for 10s... ===" >&2
-    fi
-  fi
-
-  # Advance offset past all updates
-  NEW_LAST=$(echo "$UPDATES" | jq -r '.result[-1].update_id // empty')
-  if [[ -n "$NEW_LAST" ]]; then
-    OFFSET=$((NEW_LAST + 1))
-  fi
-done
-
-# Acknowledge all collected updates
-curl -s "${TELEGRAM_API}/getUpdates?offset=${OFFSET}" > /dev/null
-
-echo "$COLLECTED" > "$FEEDBACK_FILE"
-echo "=== Feedback received from Telegram ===" >&2
-echo "--- Begin feedback ---" >&2
-echo "$COLLECTED" >&2
-echo "--- End feedback ---" >&2
-
-$LOOPX_BIN output --goto "apply-feedback"
diff --git a/loopx-backup/spec-test-adr/package.json b/loopx-backup/spec-test-adr/package.json
deleted file mode 100644
index 025b36b..0000000
--- a/loopx-backup/spec-test-adr/package.json
+++ /dev/null
@@ -1,7 +0,0 @@
-{
-  "type": "module",
-  "dependencies": {
-    "openai": "^6.0.0",
-    "tsx": "^4.19.3"
-  }
-}
diff --git a/loopx-workflows/ralph/check-ready.sh b/loopx-workflows/ralph/check-ready.sh
deleted file mode 100755
index 1296b5c..0000000
--- a/loopx-workflows/ralph/check-ready.sh
+++ /dev/null
@@ -1,33 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-ROOT="$LOOPX_PROJECT_ROOT"
-ITER_FILE="$ROOT/.loopx/.iteration.tmp"
-
-: "${TELEGRAM_BOT_TOKEN:?TELEGRAM_BOT_TOKEN env var is required}"
-: "${TELEGRAM_CHAT_ID:?TELEGRAM_CHAT_ID env var is required}"
-
-TELEGRAM_API="https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}"
-
-RALPH_OUTPUT=$(cat)
-
-REVIEW_PROMPT=$(printf 'The following is the stdout of one iteration of an agent development loop. Judge whether the output itself states or clearly indicates that the work is production ready / complete / done. Only answer READY if the output affirmatively claims production readiness. Reply with exactly one word: READY or NOT_READY.\n\n--- begin output ---\n%s\n--- end output ---' "$RALPH_OUTPUT")
-
-VERDICT=$(echo "$REVIEW_PROMPT" | claude -p --dangerously-skip-permissions 2>/dev/null)
-
-echo "=== Readiness verdict: ${VERDICT} ===" >&2
-
-if echo "$VERDICT" | grep -qw "READY"; then
-  ITER=$(cat "$ITER_FILE" 2>/dev/null || echo "?")
-
-  curl -s -X POST "${TELEGRAM_API}/sendMessage" \
-    -d chat_id="$TELEGRAM_CHAT_ID" \
-    --data-urlencode "text=Ralph loop: production ready after iteration ${ITER}. Halting." > /dev/null
-
-  rm -f "$ITER_FILE"
-  echo "=== Production ready — halting loop ===" >&2
-  $LOOPX_BIN output --result "Production ready after iteration ${ITER}." --stop
-else
-  echo "=== Not production ready — continuing loop ===" >&2
-  $LOOPX_BIN output --result "continuing" --goto "run-ralph"
-fi
diff --git a/loopx-workflows/ralph/package.json b/loopx-workflows/ralph/package.json
deleted file mode 100644
index 089153b..0000000
--- a/loopx-workflows/ralph/package.json
+++ /dev/null
@@ -1 +0,0 @@
-{"type":"module"}
diff --git a/loopx-workflows/ralph/run-ralph.sh b/loopx-workflows/ralph/run-ralph.sh
deleted file mode 100755
index 80398a5..0000000
--- a/loopx-workflows/ralph/run-ralph.sh
+++ /dev/null
@@ -1,33 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-ROOT="$LOOPX_PROJECT_ROOT"
-PROMPT_FILE="$ROOT/PROMPT.md"
-ITER_FILE="$ROOT/.loopx/.iteration.tmp"
-
-: "${TELEGRAM_BOT_TOKEN:?TELEGRAM_BOT_TOKEN env var is required}"
-: "${TELEGRAM_CHAT_ID:?TELEGRAM_CHAT_ID env var is required}"
-
-TELEGRAM_API="https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}"
-
-if [[ ! -f "$PROMPT_FILE" ]]; then
-  echo "Error: PROMPT.md not found at $PROMPT_FILE" >&2
-  exit 1
-fi
-
-if [[ -f "$ITER_FILE" ]]; then
-  ITER=$(($(cat "$ITER_FILE") + 1))
-else
-  ITER=1
-fi
-echo "$ITER" > "$ITER_FILE"
-
-curl -s -X POST "${TELEGRAM_API}/sendMessage" \
-  -d chat_id="$TELEGRAM_CHAT_ID" \
-  --data-urlencode "text=Ralph loop: starting iteration ${ITER}" > /dev/null
-
-echo "=== Ralph iteration ${ITER} ===" >&2
-
-RALPH_OUTPUT=$(cat "$PROMPT_FILE" | claude -p --dangerously-skip-permissions 2>/dev/null)
-
-$LOOPX_BIN output --result "$RALPH_OUTPUT" --goto "check-ready"