forge-orkes 0.64.0 → 0.64.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.64.0",
+  "version": "0.64.2",
   "description": "Set up the Forge meta-prompting framework for Claude Code in your project",
   "bin": {
     "create-forge": "./bin/create-forge.js"

package/template/.claude/skills/jarvis/SKILL.md

@@ -164,7 +164,7 @@ RC on-demand `--spawn worktree` sessions leave `.claude/worktrees/bridge-{cse-id
 .forge/checks/forge-jarvis-bridge-clean.sh               # then reap
 ```
 
-Liveness is best-effort (dirty **or** freshly-modified = keep) with `git worktree remove` refusing a dirty worktree as a second net; only `bridge-*` basenames are ever eligible. Run it as light housekeeping, not on a timer — there is no daemon.
+Liveness is decided in this order (FR-207 gap-closure): dirty = keep; a git lock naming a **live** server pid = keep; a lock with a **dead** pid = orphan even when freshly modified (unlock-then-remove — RC locks every spawned bridge under the server's pid, so a fresh-looking bridge whose server died is still reapable); mtime freshness applies only to **unlocked** bridges. `git worktree remove` refusing a dirty worktree stays the second net; only `bridge-*` basenames are ever eligible. Run it as light housekeeping, not on a timer — there is no daemon.
 
 ### The hub trigger stays watched, not built
 
@@ -181,7 +181,7 @@ The last thing Jarvis does — and the sharpest boundary. On the operator's **ex
 
 The helper does exactly two things, in order:
 
-1. **Shows what the SHA carries** — recomputed live from the board projection (and the fold), never a session's word. The merged-but-not-yet-validated units are the ones this promotion covers, **by containment**: a unit becomes `validated` when its landed SHA is an ancestor of the signed `promotion/<sha>` tag's commit (ADR-024), verified offline on the host.
+1. **Shows what the SHA carries** — recomputed live from the board projection (whose rows carry the fold-derived `release_state`), never a session's word. The merged-but-not-yet-validated units are the ones this promotion covers, **by containment**: a unit becomes `validated` when its landed SHA is an ancestor of the signed `promotion/<sha>` tag's commit (ADR-024), verified offline on the host.
 2. **Triggers the step-2 seam** — `gh workflow run promote.yml -f sha=<full-sha>` — and stops. The flow halts at GitHub's Environment gates (both taps: deploy + mint) until you press them there.
 
 ### Jarvis never approves — it refuses if asked

package/template/.forge/checks/forge-jarvis-answer.sh

@@ -29,7 +29,6 @@ SELF_DIR="$(cd "$(dirname "$0")" && pwd)"
 DISPATCH="${FORGE_JARVIS_DISPATCH:-$SELF_DIR/forge-jarvis-dispatch.sh}"
 
 WORK_DIR=""; PHASE=""; SLICE=""; ANSWER=""; ANSWER_FILE=""; DRY=0
-FWD=""
 while [ $# -gt 0 ]; do
   case "$1" in
     --work-dir)    WORK_DIR="${2:-}"; shift 2 ;;
@@ -38,14 +37,22 @@ while [ $# -gt 0 ]; do
     --answer)      ANSWER="${2:-}"; shift 2 ;;
     --answer-file) ANSWER_FILE="${2:-}"; shift 2 ;;
     --dry-run)     DRY=1; shift ;;
-    --)            shift; FWD="$*"; break ;;
-    *) shift ;;
+    --)            shift; break ;;
+    *) printf 'forge-jarvis-answer: unknown argument: %s\n' "$1" >&2; exit 2 ;;
   esac
 done
+# After `--`, the remaining "$@" is forwarded to dispatch verbatim — argument
+# boundaries preserved (never flattened to a string; args with spaces survive).
 
 [ -n "$WORK_DIR" ] && [ -n "$PHASE" ] && [ -n "$SLICE" ] || {
   printf 'forge-jarvis-answer: --work-dir, --phase and --slice are all required\n' >&2; exit 2; }
 
+# The phase index comes from a park ping (semi-trusted runner log) and is built
+# into a write path — a non-numeric value could traverse out of the work dir.
+case "$PHASE" in
+  *[!0-9]*|'') printf 'forge-jarvis-answer: --phase must be a numeric phase index, got: %s\n' "$PHASE" >&2; exit 2 ;;
+esac
+
 # Resolve the answer text: --answer, else --answer-file, else stdin.
 if [ -z "$ANSWER" ]; then
   if [ -n "$ANSWER_FILE" ] && [ -f "$ANSWER_FILE" ]; then
@@ -65,7 +72,7 @@ DEST="$WORK_DIR/phase-$PHASE/answer.md"        # the EXACT m-35 convention
 
 if [ "$DRY" = 1 ]; then
   printf 'answer plan: write → %s ; then re-dispatch %s --slice %s --work-dir %s %s\n' \
-    "$DEST" "$DISPATCH" "$SLICE" "$WORK_DIR" "$FWD"
+    "$DEST" "$DISPATCH" "$SLICE" "$WORK_DIR" "$*"
   exit 0
 fi
 
@@ -75,5 +82,4 @@ printf '%s\n' "$ANSWER" > "$DEST" || { printf 'forge-jarvis-answer: could not wr
 printf 'forge-jarvis-answer: answer landed at %s\n' "$DEST" >&2
 
 # 2) re-dispatch the slice so the runner resumes past the park (m-35 prompt re-assembly)
-# shellcheck disable=SC2086
-"$DISPATCH" --slice "$SLICE" --work-dir "$WORK_DIR" $FWD
+"$DISPATCH" --slice "$SLICE" --work-dir "$WORK_DIR" "$@"

package/template/.forge/checks/forge-jarvis-awareness.sh

@@ -47,7 +47,7 @@ while [ $# -gt 0 ]; do
   case "$1" in
     --dry-run)       DRY_RUN=1; shift ;;
     --worktree-root) WT_ROOT="${2:-}"; shift 2 ;;
-    *) shift ;;
+    *) printf 'forge-jarvis-awareness: unknown argument: %s\n' "$1" >&2; exit 2 ;;
   esac
 done
 
@@ -73,7 +73,7 @@ list_slices() {
     done
   else
     git -C "$REPO_ROOT" worktree list --porcelain 2>/dev/null | awk -v tab="$TAB" '
-      /^worktree / { p = $2 }
+      /^worktree / { p = substr($0, 10) }   # full remainder — paths may contain spaces
       /^branch /   {
         if ($2 ~ /refs\/heads\/forge\/m-/) {
           b = $2; sub(/refs\/heads\//, "", b)          # forge/m-37[-<session>]
@@ -108,9 +108,14 @@ elif [ -f "$BOARD" ]; then
     # no jq dependency (Article X native-first).
     _inflight="$(printf '%s\n' "$_emit" | grep '"forge_id"' | grep -vE '"status":[[:space:]]*"complete"')"
     if [ -n "$_inflight" ]; then
-      printf '%s\n' "$_inflight" \
-        | sed -E 's/.*"forge_id":[[:space:]]*"([^"]+)".*"status":[[:space:]]*"([^"]+)".*"release_state":[[:space:]]*"([^"]+)".*/   \1  status=\2  release_state=\3/' \
-        | head -40
+      # Order-independent field extraction — one sed per key, so a key-order change
+      # in the board emit degrades a field to '?' instead of silently dropping the line.
+      printf '%s\n' "$_inflight" | head -40 | while IFS= read -r _ln; do
+        _id="$(printf '%s' "$_ln" | sed -n 's/.*"forge_id":[[:space:]]*"\([^"]*\)".*/\1/p')"
+        _st="$(printf '%s' "$_ln" | sed -n 's/.*"status":[[:space:]]*"\([^"]*\)".*/\1/p')"
+        _rs="$(printf '%s' "$_ln" | sed -n 's/.*"release_state":[[:space:]]*"\([^"]*\)".*/\1/p')"
+        printf '   %s  status=%s  release_state=%s\n' "${_id:-?}" "${_st:-?}" "${_rs:-?}"
+      done
     else
       printf '   (all board units complete — nothing in flight)\n'
     fi

package/template/.forge/checks/forge-jarvis-bridge-clean.sh

@@ -24,7 +24,8 @@
 #   forge-jarvis-bridge-clean.sh [--dry-run] [--stale-hours N] [--worktrees-root <dir>]
 #     --dry-run          list orphan candidates; remove NOTHING (default is to remove).
 #     --stale-hours N    freshness window; a bridge modified within N hours is LIVE (default 6).
-#     --worktrees-root   override the scan root (tests); default: <repo>/.claude/worktrees.
+#     --worktree-root    override the scan root (tests); default: <repo>/.claude/worktrees.
+#                        (--worktrees-root accepted as an alias — historical spelling.)
 set -u
 
 SELF_DIR="$(cd "$(dirname "$0")" && pwd)"
@@ -37,8 +38,10 @@ while [ $# -gt 0 ]; do
   case "$1" in
     --dry-run)         DRY_RUN=1; shift ;;
     --stale-hours)     STALE_HOURS="${2:-6}"; shift 2 ;;
-    --worktrees-root)  WT_ROOT="${2:-}"; shift 2 ;;
-    *) shift ;;
+    # both spellings accepted — the family standard is --worktree-root (relay/awareness/
+    # instruments); the plural was this script's original flag and stays as an alias.
+    --worktree-root|--worktrees-root) WT_ROOT="${2:-}"; shift 2 ;;
+    *) printf 'forge-jarvis-bridge-clean: unknown argument: %s\n' "$1" >&2; exit 2 ;;
   esac
 done
 [ -n "$WT_ROOT" ] || WT_ROOT="$REPO_ROOT/.claude/worktrees"

package/template/.forge/checks/forge-jarvis-dispatch.sh

@@ -121,18 +121,40 @@ materialize_work_order() {
     fi
   fi
   _tmp="$WORKTREE/slice.yml.tmp"
+  # Write-target hygiene: refuse a pre-existing tmp (incl. a pre-committed symlink —
+  # a redirect would follow it and truncate whatever it points at).
+  if [ -e "$_tmp" ] || [ -L "$_tmp" ]; then
+    printf 'forge-jarvis-dispatch: REFUSED — %s already exists; remove it and re-dispatch. RELAY this refusal to the operator.\n' "$_tmp" >&2
+    return 2
+  fi
   printf '# Materialized by forge-jarvis-dispatch from %s (delete to re-materialize)\nphases:\n' "${_mdir#"$WORKTREE"/}" > "$_tmp"
   _count=0
-  for _p in $(ls "$_mdir" 2>/dev/null | sort -n); do
-    [ -d "$_mdir/$_p" ] || continue
-    _plans="$(ls "$_mdir/$_p"/plan-*.md 2>/dev/null | sort)"
-    [ -n "$_plans" ] || continue
+  # Quoted glob iteration, numeric phase order — never word-split ls output
+  # (phase/plan names are repo content; unquoted expansion would let a crafted
+  # name pull arbitrary *.md into the runner's prompt).
+  _names=$(for _d in "$_mdir"/*/; do [ -d "$_d" ] || continue; basename "$_d"; done | sort -n)
+  while IFS= read -r _p; do
+    [ -n "$_p" ] || continue
+    _have=0
+    for _f in "$_mdir/$_p"/plan-*.md; do [ -f "$_f" ] && { _have=1; break; }; done
+    [ "$_have" = 1 ] || continue
     mkdir -p "$WORKTREE/phases/$_p"
-    # shellcheck disable=SC2086
-    cat $_plans > "$WORKTREE/phases/$_p/plan.md"
+    _pl="$WORKTREE/phases/$_p/plan.md"
+    if [ -L "$_pl" ]; then
+      rm -f "$_tmp"
+      printf 'forge-jarvis-dispatch: REFUSED — %s is a symlink; refusing to write through it. RELAY this refusal to the operator.\n' "$_pl" >&2
+      return 2
+    fi
+    : > "$_pl"
+    for _f in "$_mdir/$_p"/plan-*.md; do
+      [ -f "$_f" ] || continue
+      cat "$_f" >> "$_pl"
+    done
     printf '  - %s\n' "$_p" >> "$_tmp"
     _count=$((_count + 1))
-  done
+  done <<MATERIALIZE_EOF
+$_names
+MATERIALIZE_EOF
   if [ "$_count" -eq 0 ]; then
     rm -f "$_tmp"
     printf 'forge-jarvis-dispatch: REFUSED — %s has no phase plans (plan-*.md); nothing to dispatch. RELAY this refusal to the operator.\n' "$_mdir" >&2

package/template/.forge/checks/forge-jarvis-instruments.sh

@@ -49,7 +49,7 @@ while [ $# -gt 0 ]; do
     --since)         SINCE="${2:-}"; shift 2 ;;
     --worktree-root) WT_ROOT="${2:-}"; shift 2 ;;
     --dry-run)       DRY_RUN=1; shift ;;
-    *) shift ;;
+    *) printf 'forge-jarvis-instruments: unknown argument: %s\n' "$1" >&2; exit 2 ;;
   esac
 done
 
@@ -70,12 +70,15 @@ if [ -z "$LOGS" ]; then
     done
   else
     _globbed="$(git -C "$REPO_ROOT" worktree list --porcelain 2>/dev/null | awk '
-      /^worktree / { p = $2 }
+      /^worktree / { p = substr($0, 10) }   # full remainder — paths may contain spaces
       /^branch /   { if ($2 ~ /refs\/heads\/forge\/m-/) print p "/.forge/runner-work/notify.log" }')"
-    for _l in $_globbed; do
+    while IFS= read -r _l; do
+      [ -n "$_l" ] || continue
       [ -f "$_l" ] && LOGS="${LOGS}${LOGS:+
 }$_l"
-    done
+    done <<GLOBBED_EOF
+$_globbed
+GLOBBED_EOF
   fi
 fi
 

package/template/.forge/checks/forge-jarvis-notify-logonly.sh

@@ -30,6 +30,12 @@ set -u
 TYPE="${1:-note}"
 PAYLOAD="${2:-}"
 
+# The log is TAB-separated, one ping per line, and the relay parses it as such —
+# scrub field-forging bytes from caller input so a crafted payload cannot mint
+# extra pings or extra fields (noise-bounded anyway: state claims are host-recomputed).
+TYPE=$(printf '%s' "$TYPE" | tr '\n\t' '  ')
+PAYLOAD=$(printf '%s' "$PAYLOAD" | tr '\n\t' '  ')
+
 # Durable local record — the ONLY thing this channel does. Default location travels with
 # the slice (FORGE_SLICE_WORK_DIR), but a Jarvis dispatch always sets FORGE_SLICE_NOTIFY_LOG
 # explicitly INTO the slice worktree.

package/template/.forge/checks/forge-jarvis-promote.sh

@@ -3,10 +3,11 @@
 # handoff-step4-jarvis.md REV2; FR-208; NFR-038; operator ruling 3 "trigger-not-approve").
 #
 # The operator says "promote <sha>". Jarvis does exactly two things, in order:
-#   1. SHOW what that SHA carries — recomputed from HOST truth (the board projection + the
-#      fold), never a session's word. The merged-but-not-yet-validated units are the ones a
-#      promotion covers, by CONTAINMENT: a unit becomes validated when its landed SHA is an
-#      ancestor of the signed promotion tag's commit (ADR-024) — verified offline, host-side.
+#   1. SHOW what that SHA carries — recomputed from HOST truth (the board projection, whose
+#      rows carry fold-derived release_state), never a session's word. The merged-but-not-yet-
+#      validated units are the ones a promotion covers, by CONTAINMENT: a unit becomes
+#      validated when its landed SHA is an ancestor of the signed promotion tag's commit
+#      (ADR-024) — verified offline, host-side.
 #   2. TRIGGER the step-2 seam:  gh workflow run promote.yml -f sha=<full-sha>
 #
 # That is ALL it does. It NEVER approves, waives, or lowers anything: the flow STOPS at
@@ -22,8 +23,8 @@
 #     --dry-run    SHOW host state, then PRINT the trigger command without running it.
 #
 # HOST-TRUTH commands (env-overridable so tests inject stubs and degradation is explicit):
-#   FORGE_JARVIS_BOARD  default .forge/checks/forge-board-render.sh   (the rollup projection)
-#   FORGE_JARVIS_FOLD   default .claude/hooks/forge-release-fold.sh   (per-unit release_state)
+#   FORGE_JARVIS_BOARD  default .forge/checks/forge-board-render.sh   (the rollup projection;
+#                       its rows already carry the fold-derived release_state)
 #   FORGE_JARVIS_GH     default `gh`                                   (the trigger — never an approval)
 # BEST-EFFORT: a missing board/fold degrades to a stated '(unavailable)' — the show still
 # renders; a missing gh in a real (non-dry-run) trigger is a clear error, never a silent success.
@@ -32,7 +33,6 @@ set -u
 SELF_DIR="$(cd "$(dirname "$0")" && pwd)"
 REPO_ROOT="$(cd "$SELF_DIR/../.." && pwd)"                 # .forge/checks → repo root
 BOARD="${FORGE_JARVIS_BOARD:-$REPO_ROOT/.forge/checks/forge-board-render.sh}"
-FOLD="${FORGE_JARVIS_FOLD:-$REPO_ROOT/.claude/hooks/forge-release-fold.sh}"
 GH="${FORGE_JARVIS_GH:-gh}"
 WORKFLOW="promote.yml"
 
@@ -41,8 +41,14 @@ DRY_RUN=0
 while [ $# -gt 0 ]; do
   case "$1" in
     --dry-run) DRY_RUN=1; shift ;;
-    --*)       shift ;;                          # tolerate/ignore unknown flags
-    *)         [ -z "$SHA" ] && SHA="$1"; shift ;;
+    --*)
+      # LOUD refusal, never a silent swallow: this is the one helper where a typo'd
+      # flag (--dryrun) falling through would fire a REAL workflow trigger.
+      printf 'forge-jarvis-promote: unknown flag: %s — usage: forge-jarvis-promote.sh <full-sha> [--dry-run]\n' "$1" >&2; exit 2 ;;
+    *)
+      if [ -z "$SHA" ]; then SHA="$1"; shift; else
+        printf 'forge-jarvis-promote: unexpected extra argument: %s\n' "$1" >&2; exit 2
+      fi ;;
   esac
 done
 
@@ -65,9 +71,14 @@ if [ -f "$BOARD" ]; then
     # line-oriented JSON -> grep/sed, no jq (Article X native-first) — same parse as awareness.
     _rel="$(printf '%s\n' "$_emit" | grep '"forge_id"' | grep -E '"release_state":[[:space:]]*"(merged|validated)"')"
     if [ -n "$_rel" ]; then
-      printf '%s\n' "$_rel" \
-        | sed -E 's/.*"forge_id":[[:space:]]*"([^"]+)".*"release_state":[[:space:]]*"([^"]+)".*/   \1  release_state=\2/' \
-        | head -60
+      # Order-independent field extraction — one sed per key (kept aligned with awareness),
+      # so a key-order change in the board emit degrades a field to '?' rather than
+      # silently dropping every line into a misleading "(no merged units)".
+      printf '%s\n' "$_rel" | head -60 | while IFS= read -r _ln; do
+        _id="$(printf '%s' "$_ln" | sed -n 's/.*"forge_id":[[:space:]]*"\([^"]*\)".*/\1/p')"
+        _rs="$(printf '%s' "$_ln" | sed -n 's/.*"release_state":[[:space:]]*"\([^"]*\)".*/\1/p')"
+        printf '   %s  release_state=%s\n' "${_id:-?}" "${_rs:-?}"
+      done
     else
       printf '   (no merged units in the board projection — nothing waiting on a promotion)\n'
     fi
@@ -93,7 +104,9 @@ if ! command -v "$GH" >/dev/null 2>&1; then
 fi
 printf '   %s\n' "$CMD"
 # gh workflow run promote.yml -f sha=<full-sha> — the trigger, never an approval call.
-"$GH" workflow run "$WORKFLOW" -f sha="$SHA"
+# Pinned to REPO_ROOT: gh resolves the target repo from cwd, and this project's cwd is
+# known to snap between checkouts across turns — the trigger must always hit THIS repo.
+(cd "$REPO_ROOT" && "$GH" workflow run "$WORKFLOW" -f sha="$SHA")
 _rc=$?
 if [ "$_rc" -eq 0 ]; then
   printf '\n[ok] Triggered promote.yml for %s. It now STOPS at GitHub Environment gates — press them there; Jarvis does not.\n' "$SHA"

package/template/.forge/checks/forge-jarvis-prwatch.sh

@@ -19,7 +19,9 @@
 #   --staging-env <name>   deployment environment that means "on staging" (default: staging)
 #   --max-iterations <N>   hard poll bound (default 30)
 #   --interval <seconds>   sleep between polls (default 20; 0 = no sleep, for fixtures)
-#   --marker-dir <dir>     where the at-most-once come-try marker lives (default: cwd/.relay-markers)
+#   --marker-dir <dir>     where the at-most-once come-try marker lives
+#                          (default: <git-common-dir>/forge/relay-markers — stable across
+#                          worktrees and cwds; cwd/.relay-markers only outside a repo)
 #   --dry-run              print the resolved plan (pr, repo, env, bound) and exit; no polling
 set -u
 
@@ -35,12 +37,28 @@ while [ $# -gt 0 ]; do
     --interval)      INTERVAL="${2:-20}"; shift 2 ;;
     --marker-dir)    MARKER_DIR="${2:-}"; shift 2 ;;
     --dry-run)       DRY=1; shift ;;
-    *) shift ;;
+    *) printf 'forge-jarvis-prwatch: unknown argument: %s\n' "$1" >&2; exit 2 ;;
   esac
 done
 [ -n "$PR" ] || { printf 'forge-jarvis-prwatch: --pr <num> is required\n' >&2; exit 2; }
-[ -n "$MARKER_DIR" ] || MARKER_DIR="./.relay-markers"
-REPO_ARG=""; [ -n "$REPO" ] && REPO_ARG="--repo $REPO"
+# The PR number is carried by a runner `done` ping (semi-trusted log content) and is used
+# in the marker filename and as a gh argument — require a plain number before any use.
+case "$PR" in
+  *[!0-9]*|'') printf 'forge-jarvis-prwatch: --pr must be numeric, got: %s\n' "$PR" >&2; exit 2 ;;
+esac
+# --repo, when given, must be a plain owner/repo — anything else could smuggle gh flags.
+if [ -n "$REPO" ]; then
+  case "$REPO" in
+    */*) case "$REPO" in *[!A-Za-z0-9._/-]*|*/*/*) printf 'forge-jarvis-prwatch: --repo must be owner/repo, got: %s\n' "$REPO" >&2; exit 2 ;; esac ;;
+    *) printf 'forge-jarvis-prwatch: --repo must be owner/repo, got: %s\n' "$REPO" >&2; exit 2 ;;
+  esac
+fi
+# At-most-once marker home: stable per machine+repo (git common dir — shared across this
+# repo's worktrees, never cwd-relative droppings), falling back to cwd only outside a repo.
+if [ -z "$MARKER_DIR" ]; then
+  _cd="$(git rev-parse --git-common-dir 2>/dev/null)"
+  if [ -n "$_cd" ]; then MARKER_DIR="$_cd/forge/relay-markers"; else MARKER_DIR="./.relay-markers"; fi
+fi
 
 if [ "$DRY" = 1 ]; then
   printf 'prwatch plan: pr=%s repo=%s env=%s bound=%s×%ss marker-dir=%s\n' \
@@ -54,11 +72,10 @@ fi
 #   staging deploy → `gh api repos/{owner}/{repo}/deployments?environment=<env>` + its statuses
 # Both read host truth; neither consults anything a build session emitted.
 pr_merge_state() {   # → MERGED | CLOSED | OPEN (empty on gh error → treated as OPEN, keep polling)
-  # shellcheck disable=SC2086
-  "$GH" pr view "$PR" $REPO_ARG --json state --jq '.state' 2>/dev/null
+  # ${REPO:+…} expands to exactly two argv words when --repo was given, none otherwise.
+  "$GH" pr view "$PR" ${REPO:+--repo "$REPO"} --json state --jq '.state' 2>/dev/null
 }
 deploy_succeeded() { # → exit 0 iff the latest staging deployment is in a success state
-  # shellcheck disable=SC2086
   _st="$("$GH" api "repos/{owner}/{repo}/deployments?environment=$ENV_STAGING&per_page=1" \
            --jq '.[0].statuses_url' 2>/dev/null)"
   [ -n "$_st" ] || return 1

package/template/.forge/checks/forge-jarvis-relay.sh

@@ -32,8 +32,8 @@
 #
 # HOST-TRUTH COMMANDS (env-overridable so tests inject stubs, and so degradation is explicit):
 #   FORGE_JARVIS_FOLD   default .claude/hooks/forge-release-fold.sh  (release_state recompute)
-#   FORGE_JARVIS_GH     default `gh`                                  (PR/check facts — plan-02 leans on it)
-#   FORGE_JARVIS_BOARD  default .forge/checks/forge-board-render.sh   (rollup recompute)
+#   (gh-based facts live in forge-jarvis-prwatch.sh, which documents its own FORGE_JARVIS_GH;
+#    the board recompute lives in awareness/promote — this helper consults the fold only.)
 #
 # BEST-EFFORT: a fold/gh/board that is absent or errors degrades to release_state=unknown and
 # says so — never a silent success, never a hard fail of the relay path.
@@ -45,9 +45,12 @@ FOLD="${FORGE_JARVIS_FOLD:-$REPO_ROOT/.claude/hooks/forge-release-fold.sh}"
 
 # ── host truth: the slice's release_state, recomputed from the fold (never the payload) ───────
 host_release_state() {  # host_release_state <milestone-id>  → prints unmerged|merged|validated|unknown
+  # Kept textually aligned with fold_state in forge-jarvis-awareness.sh — same guard,
+  # same invocation, same degradation, so a fold-format change is a mechanical two-file edit.
   _mid="${1:-}"
   [ -n "$_mid" ] || { printf 'unknown'; return 0; }
-  _out="$("$FOLD" "$_mid" 2>/dev/null)" || { printf 'unknown'; return 0; }
+  [ -f "$FOLD" ] || { printf 'unknown'; return 0; }
+  _out="$(sh "$FOLD" "$_mid" 2>/dev/null)" || { printf 'unknown'; return 0; }
   _rs="$(printf '%s\n' "$_out" | grep -m1 'release_state=' | sed 's/.*release_state=//; s/[[:space:]].*//')"
   [ -n "$_rs" ] && printf '%s' "$_rs" || printf 'unknown'
 }
@@ -110,102 +113,126 @@ relay_one_line() {  # relay_one_line <tsv-line>
   build_relay_text "$_type" "$_payload"
 }
 
-# ── mode dispatch ─────────────────────────────────────────────────────────────────────────────
+# ── modes — one function per mode, each owning its own arg loop ───────────────────────────────
 MILESTONE=""
-MODE_LIVE="live"
+RELAY_MODE="live"          # 'live' | 'catchup' — how --scan emits (not a boolean)
 MARKER_DIR=""
 
-case "${1:-}" in
-  --one)
-    shift
-    LINE="${1:-}"; shift 2>/dev/null || true
-    while [ $# -gt 0 ]; do case "$1" in --milestone) MILESTONE="${2:-}"; shift 2 ;; *) shift ;; esac; done
-    relay_one_line "$LINE"; printf '\n'
-    exit 0 ;;
-
-  --list-logs)
-    # The watch set the skill arms `tail -F` on — recomputed from a DISK GLOB on EVERY call,
-    # never held in memory (Amendment 2: kill Jarvis and the armed watches re-derive from disk).
-    # Live slices are worktrees on a forge/m-* branch; each runner writes to
-    # <worktree>/.forge/runner-work/notify.log (the dispatch's FORGE_SLICE_NOTIFY_LOG). Emit the
-    # EXPECTED path even when the log does not exist yet — `tail -F` (capital F) is chosen exactly
-    # so a not-yet-created log is picked up when the first ping lands (F8).
-    shift
-    WT_ROOT=""
-    while [ $# -gt 0 ]; do case "$1" in --worktree-root) WT_ROOT="${2:-}"; shift 2 ;; *) shift ;; esac; done
-    if [ -n "$WT_ROOT" ]; then
-      # override path (tests): disk-glob the given root for slice worktrees.
-      for _wt in "$WT_ROOT"/*/; do
-        [ -d "$_wt" ] || continue
-        printf '%s.forge/runner-work/notify.log\n' "$_wt"
-      done
-    else
-      # live path: `git worktree list` is the on-disk registry of worktrees; glob it to the
-      # forge/m-* slice branches and emit each slice's notify-log path.
-      git worktree list --porcelain 2>/dev/null | awk '
-        /^worktree /  { p=$2 }
-        /^branch /    { if ($2 ~ /refs\/heads\/forge\/m-/) print p "/.forge/runner-work/notify.log" }
-      '
-    fi
-    exit 0 ;;
-
-  --audit-sources)
-    # Static guard: the done/halt (state-claim) branch must recompute from the fold, and the
-    # authoritative release-state var must NEVER be assigned from the payload. Catches a future
-    # rewrite that sources a merge verdict from the session's own payload rather than host truth.
-    # The guard's own two grep lines carry a #@audit tag and are excluded from the scan so their
-    # literal patterns cannot self-match the file they scan.
-    _body="$(grep -vE '#@audit' "$0")"
-    if ! printf '%s\n' "$_body" | grep -qE 'host_release_state|FORGE_JARVIS_FOLD|forge-release-fold'; then  #@audit
-      printf 'forge-jarvis-relay: AUDIT FAIL — no host-truth (fold) recompute in the relay path\n' >&2
-      exit 3
-    fi
-    if printf '%s\n' "$_body" | grep -qE '_rs=["'\''$]*_payload'; then  #@audit
-      printf 'forge-jarvis-relay: AUDIT FAIL — a state claim is sourced from the payload, not the host\n' >&2
-      exit 3
-    fi
-    printf 'relay speaks host truth only\n'
-    exit 0 ;;
+mode_one() {
+  LINE="${1:-}"; shift 2>/dev/null || true
+  while [ $# -gt 0 ]; do case "$1" in
+    --milestone) MILESTONE="${2:-}"; shift 2 ;;
+    *) printf 'forge-jarvis-relay: unknown argument: %s\n' "$1" >&2; exit 2 ;;
+  esac; done
+  relay_one_line "$LINE"; printf '\n'
+  exit 0
+}
 
-  --scan)
-    shift
-    LOG="${1:-}"; shift 2>/dev/null || true
-    while [ $# -gt 0 ]; do
-      case "$1" in
-        --marker-dir) MARKER_DIR="${2:-}"; shift 2 ;;
-        --milestone)  MILESTONE="${2:-}"; shift 2 ;;
-        --mode)       MODE_LIVE="${2:-live}"; shift 2 ;;
-        *) shift ;;
-      esac
+mode_list_logs() {
+  # The watch set the skill arms `tail -F` on — recomputed from a DISK GLOB on EVERY call,
+  # never held in memory (Amendment 2: kill Jarvis and the armed watches re-derive from disk).
+  # Live slices are worktrees on a forge/m-* branch; each runner writes to
+  # <worktree>/.forge/runner-work/notify.log (the dispatch's FORGE_SLICE_NOTIFY_LOG). Emit the
+  # EXPECTED path even when the log does not exist yet — `tail -F` (capital F) is chosen exactly
+  # so a not-yet-created log is picked up when the first ping lands (F8).
+  WT_ROOT=""
+  while [ $# -gt 0 ]; do case "$1" in
+    --worktree-root) WT_ROOT="${2:-}"; shift 2 ;;
+    *) printf 'forge-jarvis-relay: unknown argument: %s\n' "$1" >&2; exit 2 ;;
+  esac; done
+  if [ -n "$WT_ROOT" ]; then
+    # override path (tests): disk-glob the given root for slice worktrees.
+    for _wt in "$WT_ROOT"/*/; do
+      [ -d "$_wt" ] || continue
+      printf '%s.forge/runner-work/notify.log\n' "$_wt"
     done
-    [ -n "$LOG" ] && [ -f "$LOG" ] || { printf 'forge-jarvis-relay: --scan needs an existing logfile\n' >&2; exit 2; }
-    [ -n "$MARKER_DIR" ] || MARKER_DIR="$(dirname "$LOG")/relay-markers"
-    mkdir -p "$MARKER_DIR" 2>/dev/null || true
+  else
+    # live path: `git worktree list` is the on-disk registry of worktrees; glob it to the
+    # forge/m-* slice branches and emit each slice's notify-log path. Pinned with -C so the
+    # watch list never depends on the caller's cwd (the cwd-reset footgun: a snapped cwd
+    # would silently arm ZERO watches).
+    git -C "$REPO_ROOT" worktree list --porcelain 2>/dev/null | awk '
+      /^worktree /  { p=substr($0, 10) }   # full remainder — paths may contain spaces
+      /^branch /    { if ($2 ~ /refs\/heads\/forge\/m-/) print p "/.forge/runner-work/notify.log" }
+    '
+  fi
+  exit 0
+}
 
-    _n=0; _fresh=0; _summary=""
-    # Read every line; relay only those whose offset (line number) has no marker yet.
-    while IFS= read -r _l || [ -n "$_l" ]; do
-      _n=$((_n + 1))
-      _marker="$MARKER_DIR/$_n.relayed"
-      [ -f "$_marker" ] && continue                      # at-most-once: already relayed, never re-buzz
-      _text="$(relay_one_line "$_l")"
-      # Write the marker BEFORE emitting — a crash after emit must not double-buzz; a crash
-      # before emit leaves it unmarked and it re-surfaces as while-you-were-away (no silent loss).
-      printf '%s\toffset=%s\t%s\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null || echo now)" "$_n" "$_text" > "$_marker" 2>/dev/null || true
-      _fresh=$((_fresh + 1))
-      if [ "$MODE_LIVE" = catchup ]; then
-        _summary="${_summary}${_summary:+ | }$_text"
-      else
-        printf '%s\n' "$_text"                            # live: one relay text per new ping → one buzz
-      fi
-    done < "$LOG"
+mode_audit_sources() {
+  # Static guard: the done/halt (state-claim) branch must recompute from the fold, and the
+  # authoritative release-state var must NEVER be assigned from the payload. Catches a future
+  # rewrite that sources a merge verdict from the session's own payload rather than host truth.
+  # The guard's own two grep lines carry a #@audit tag and are excluded from the scan so their
+  # literal patterns cannot self-match the file they scan.
+  _body="$(grep -vE '#@audit' "$0")"
+  if ! printf '%s\n' "$_body" | grep -qE 'host_release_state|FORGE_JARVIS_FOLD|forge-release-fold'; then  #@audit
+    printf 'forge-jarvis-relay: AUDIT FAIL — no host-truth (fold) recompute in the relay path\n' >&2
+    exit 3
+  fi
+  if printf '%s\n' "$_body" | grep -qE '_rs=["'\''$]*_payload'; then  #@audit
+    printf 'forge-jarvis-relay: AUDIT FAIL — a state claim is sourced from the payload, not the host\n' >&2
+    exit 3
+  fi
+  printf 'relay speaks host truth only\n'
+  exit 0
+}
+
+mode_scan() {
+  LOG="${1:-}"; shift 2>/dev/null || true
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --marker-dir) MARKER_DIR="${2:-}"; shift 2 ;;
+      --milestone)  MILESTONE="${2:-}"; shift 2 ;;
+      --mode)       RELAY_MODE="${2:-live}"; shift 2 ;;
+      *) printf 'forge-jarvis-relay: unknown argument: %s\n' "$1" >&2; exit 2 ;;
+    esac
+  done
+  [ -n "$LOG" ] || { printf 'forge-jarvis-relay: --scan needs a logfile path\n' >&2; exit 2; }
+  # A dispatched-but-not-yet-pinged slice has no log YET — --list-logs deliberately emits
+  # expected paths, so catchup over that set must compose: a missing log is an EMPTY log
+  # (nothing to relay, exit 0), never a refusal. A missing path ARGUMENT stays exit 2 above.
+  [ -f "$LOG" ] || exit 0
+  [ -n "$MARKER_DIR" ] || MARKER_DIR="$(dirname "$LOG")/relay-markers"
+  mkdir -p "$MARKER_DIR" 2>/dev/null || true
 
-    if [ "$MODE_LIVE" = catchup ] && [ "$_fresh" -gt 0 ]; then
-      printf '📨 While you were away — %s ping(s): %s\n' "$_fresh" "$_summary"
+  _n=0; _fresh=0; _summary=""
+  # Read every line; relay only those whose offset (line number) has no marker yet.
+  while IFS= read -r _l || [ -n "$_l" ]; do
+    _n=$((_n + 1))
+    _marker="$MARKER_DIR/$_n.relayed"
+    [ -f "$_marker" ] && continue                      # at-most-once: already relayed, never re-buzz
+    _text="$(relay_one_line "$_l")"
+    # Write the marker BEFORE emitting — a crash after emit must not double-buzz; a crash
+    # before emit leaves it unmarked and it re-surfaces as while-you-were-away (no silent loss).
+    # A FAILED marker write must not emit either: emitting unmarked would re-buzz on every
+    # scan (at-most-once silently inverted). Say so loudly and skip — the ping stays unmarked
+    # and re-surfaces once the marker dir is fixed.
+    if ! printf '%s\toffset=%s\t%s\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null || echo now)" "$_n" "$_text" > "$_marker" 2>/dev/null; then
+      printf 'forge-jarvis-relay: WARNING — cannot write marker %s; relay of line %s SUPPRESSED to preserve at-most-once. Fix the marker dir.\n' "$_marker" "$_n" >&2
+      continue
+    fi
+    _fresh=$((_fresh + 1))
+    if [ "$RELAY_MODE" = catchup ]; then
+      _summary="${_summary}${_summary:+ | }$_text"
+    else
+      printf '%s\n' "$_text"                            # live: one relay text per new ping → one buzz
     fi
-    # exit 0 whether or not anything was fresh (a no-op scan is success, not failure).
-    exit 0 ;;
+  done < "$LOG"
 
+  if [ "$RELAY_MODE" = catchup ] && [ "$_fresh" -gt 0 ]; then
+    printf '📨 While you were away — %s ping(s): %s\n' "$_fresh" "$_summary"
+  fi
+  # exit 0 whether or not anything was fresh (a no-op scan is success, not failure).
+  exit 0
+}
+
+# ── mode dispatch ─────────────────────────────────────────────────────────────────────────────
+case "${1:-}" in
+  --one)           shift; mode_one "$@" ;;
+  --list-logs)     shift; mode_list_logs "$@" ;;
+  --audit-sources) shift; mode_audit_sources ;;
+  --scan)          shift; mode_scan "$@" ;;
   *)
     printf 'usage: forge-jarvis-relay.sh --one "<tsv-line>" [--milestone m-N]\n' >&2
     printf '       forge-jarvis-relay.sh --scan <logfile> [--marker-dir <dir>] [--milestone m-N] [--mode live|catchup]\n' >&2

package/template/.forge/checks/forge-jarvis.sh

@@ -115,6 +115,13 @@ else
   SUFFIX="${FORGE_JARVIS_NAME_SUFFIX:-$(jarvis_cfg name_suffix)}"
   [ -n "$SUFFIX" ] && NAME="$NAME-$SUFFIX"
 fi
+# The resolved name reaches the phone's session list AND the --dry-run line the
+# operator may copy-paste — keep it to a safe, phone-legible charset regardless of
+# where it came from (override flag, config name_suffix, env).
+case "$NAME" in
+  *[!A-Za-z0-9._-]*|'')
+    printf 'forge-jarvis: sticky name must be [A-Za-z0-9._-] only, got: %s\n' "$NAME" >&2; exit 2 ;;
+esac
 
 # --- capacity ----------------------------------------------------------------
 CAP="${CAP_OVERRIDE:-$(jarvis_cfg capacity)}"
@@ -124,25 +131,19 @@ case "$CAP" in
 esac
 
 # --- resolve -----------------------------------------------------------------
-# Printed exactly as executed (modulo the caffeinate degradation below).
-RESOLVED="caffeinate -s claude remote-control --name $NAME --spawn worktree --capacity $CAP"
+# The ONE command shape, built once — --dry-run prints exactly the argv launch
+# execs (modulo the caffeinate degradation below), so the two can never drift.
+set -- claude remote-control --name "$NAME" --spawn worktree --capacity "$CAP"
 
 if [ "$DRY_RUN" = "1" ]; then
-  printf '%s\n' "$RESOLVED"
+  printf 'caffeinate -s %s\n' "$*"
   exit 0
 fi
 
-# ============================================================================
-# B4 SEAM — DO NOT REMOVE (contract B4(a)).
-# At boot Jarvis arms a Monitor tail (`tail -F` — capital F) on each active
-# slice's notify log, the watch list recomputed by globbing live slice
-# worktrees, never from memory (Amendment 2). That boot arming act attaches
-# HERE — as the launcher's instruction to the pre-created session — once the
-# relay (B4) exists. Deliberately a no-op today: B2 ships the presence only,
-# and building any relay glue ahead of B4 is out of this phase's scope.
-# ============================================================================
-jarvis_boot_arm() { :; }
-jarvis_boot_arm
+# Boot arming (contract B4(a)) is the PRE-CREATED SESSION's act, not the launcher's:
+# the session arms Monitor `tail -F` watches on the live notify logs per
+# .claude/skills/jarvis/SKILL.md ("Session binding" / arm-the-watches). The launcher
+# stays presence-only and deliberately keeps no relay glue.
 
 # --- launch ------------------------------------------------------------------
 command -v claude >/dev/null 2>&1 || {
@@ -152,9 +153,9 @@ command -v claude >/dev/null 2>&1 || {
 printf 'forge-jarvis: starting %s (capacity %s) in %s\n' "$NAME" "$CAP" "$ROOT" >&2
 cd "$ROOT" || exit 2
 if command -v caffeinate >/dev/null 2>&1; then
-  exec caffeinate -s claude remote-control --name "$NAME" --spawn worktree --capacity "$CAP"
+  exec caffeinate -s "$@"
 else
   # non-macOS: no caffeinate — launch unwrapped; sleep then queues-until-wake (probe iii).
   printf 'forge-jarvis: caffeinate not found — launching without keep-awake (lid-closed autonomy degrades to queue-until-wake).\n' >&2
-  exec claude remote-control --name "$NAME" --spawn worktree --capacity "$CAP"
+  exec "$@"
 fi

package/template/.forge/checks/tests/forge-jarvis-awareness.test.sh

@@ -0,0 +1,118 @@
+#!/usr/bin/env sh
+# Fixture test for .forge/checks/forge-jarvis-awareness.sh (m-37 B5; FR-203/204, NFR-036).
+#
+# Pins the B5 "what's in play?" surface that shipped untested: the slice glob
+# (--worktree-root seam), per-slice fold recompute + degradation, the board
+# projection parse (including key-order independence) + degradation, the
+# always-present per-machine caveat, and the loud unknown-flag refusal.
+# No real repo/network — pure fixtures via the existing env seams.
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+AWARE="$SCRIPT_DIR/../forge-jarvis-awareness.sh"
+[ -f "$AWARE" ] || printf 'NOTE: %s missing — RED phase, every case should FAIL\n' "$AWARE" >&2
+
+ROOT="$(mktemp -d)"
+trap 'rm -rf "$ROOT"' EXIT INT TERM
+
+PASSED=0; FAILED=0
+ok()  { PASSED=$((PASSED+1)); printf '  ok   %s\n' "$1"; }
+bad() { FAILED=$((FAILED+1)); printf '  FAIL %s\n     %s\n' "$1" "$2"; }
+
+# fixture slice worktrees (the --worktree-root seam globs this dir)
+WT="$ROOT/worktrees"; mkdir -p "$WT/m-41" "$WT/m-42"
+
+# stub fold: records invocation, answers a fixed state
+FOLDSTUB="$ROOT/fold.sh"
+cat > "$FOLDSTUB" <<'EOF'
+#!/bin/sh
+echo "called $1" >> "${FOLD_CALLS:-/dev/null}"
+echo "release_state=merged"
+EOF
+chmod +x "$FOLDSTUB"
+
+# stub board: two units, one complete one executing — and the executing row uses a
+# DIFFERENT key order (release_state before status) to pin the order-independent parse.
+BOARDSTUB="$ROOT/board.sh"
+cat > "$BOARDSTUB" <<'EOF'
+#!/bin/sh
+[ "$1" = "--emit" ] || exit 2
+printf '{"forge_id": "m-40", "status": "complete", "release_state": "validated"}\n'
+printf '{"forge_id": "m-41", "release_state": "unmerged", "status": "executing"}\n'
+EOF
+chmod +x "$BOARDSTUB"
+
+# 1. --dry-run: slices listed, fold NOT invoked
+CALLS="$ROOT/fold-calls"; : > "$CALLS"
+OUT="$(FOLD_CALLS="$CALLS" FORGE_JARVIS_FOLD="$FOLDSTUB" FORGE_JARVIS_BOARD="$BOARDSTUB" \
+       sh "$AWARE" --dry-run --worktree-root "$WT" 2>&1)"
+if printf '%s' "$OUT" | grep -q 'm-41' && printf '%s' "$OUT" | grep -q '(dry-run)' && [ ! -s "$CALLS" ]; then
+  ok '--dry-run lists slices without invoking the fold'
+else
+  bad '--dry-run lists slices without invoking the fold' "$OUT"
+fi
+
+# 2. real run: per-slice fold recompute rendered
+OUT="$(FOLD_CALLS="$CALLS" FORGE_JARVIS_FOLD="$FOLDSTUB" FORGE_JARVIS_BOARD="$BOARDSTUB" \
+       sh "$AWARE" --worktree-root "$WT" 2>&1)"
+if printf '%s' "$OUT" | grep -q 'release_state=merged' && grep -q 'called m-41' "$CALLS"; then
+  ok 'live run recomputes each slice release_state from the fold'
+else
+  bad 'live run recomputes each slice release_state from the fold' "$OUT"
+fi
+
+# 3. fold missing → unknown, exit 0 (degraded, never fatal)
+OUT="$(FORGE_JARVIS_FOLD="$ROOT/no-such-fold" FORGE_JARVIS_BOARD="$BOARDSTUB" \
+       sh "$AWARE" --worktree-root "$WT" 2>&1)"; RC=$?
+if [ "$RC" -eq 0 ] && printf '%s' "$OUT" | grep -q 'release_state=unknown'; then
+  ok 'missing fold degrades to release_state=unknown, exit 0'
+else
+  bad 'missing fold degrades to release_state=unknown, exit 0' "rc=$RC out=$OUT"
+fi
+
+# 4. board projection: in-flight only, key-order-independent field extraction
+OUT="$(FORGE_JARVIS_FOLD="$FOLDSTUB" FORGE_JARVIS_BOARD="$BOARDSTUB" \
+       sh "$AWARE" --worktree-root "$WT" 2>&1)"
+if printf '%s' "$OUT" | grep -q 'm-41  status=executing  release_state=unmerged' \
+   && ! printf '%s' "$OUT" | grep -q 'm-40  status=complete'; then
+  ok 'board parse: in-flight only, fields extracted regardless of key order'
+else
+  bad 'board parse: in-flight only, fields extracted regardless of key order' "$OUT"
+fi
+
+# 5. board missing → stated unavailable, exit 0
+OUT="$(FORGE_JARVIS_FOLD="$FOLDSTUB" FORGE_JARVIS_BOARD="$ROOT/no-such-board" \
+       sh "$AWARE" --worktree-root "$WT" 2>&1)"; RC=$?
+if [ "$RC" -eq 0 ] && printf '%s' "$OUT" | grep -qi 'projection unavailable'; then
+  ok 'missing board degrades to a stated unavailable, exit 0'
+else
+  bad 'missing board degrades to a stated unavailable, exit 0' "rc=$RC out=$OUT"
+fi
+
+# 6. per-machine caveat always present (F11)
+if printf '%s' "$OUT" | grep -q 'PER-MACHINE'; then
+  ok 'per-machine scope caveat is always stated'
+else
+  bad 'per-machine scope caveat is always stated' "$OUT"
+fi
+
+# 7. empty worktree root → explicit none-line, exit 0
+EMPTY="$ROOT/empty"; mkdir -p "$EMPTY"
+OUT="$(FORGE_JARVIS_FOLD="$FOLDSTUB" FORGE_JARVIS_BOARD="$BOARDSTUB" \
+       sh "$AWARE" --worktree-root "$EMPTY" 2>&1)"; RC=$?
+if [ "$RC" -eq 0 ] && printf '%s' "$OUT" | grep -q '(none on this machine)'; then
+  ok 'empty glob renders an explicit none-line, not silence'
+else
+  bad 'empty glob renders an explicit none-line, not silence' "rc=$RC out=$OUT"
+fi
+
+# 8. unknown flag → loud refusal, exit 2
+OUT="$(sh "$AWARE" --no-such-flag 2>&1)"; RC=$?
+if [ "$RC" -eq 2 ] && printf '%s' "$OUT" | grep -q 'unknown argument'; then
+  ok 'unknown flag refused loudly (exit 2)'
+else
+  bad 'unknown flag refused loudly (exit 2)' "rc=$RC out=$OUT"
+fi
+
+printf '\nforge-jarvis-awareness.test.sh: %s passed, %s failed\n' "$PASSED" "$FAILED"
+[ "$FAILED" -eq 0 ]

package/template/.forge/checks/tests/forge-jarvis-notify-logonly.test.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env sh
+# Fixture test for .forge/checks/forge-jarvis-notify-logonly.sh (m-37 B3; FR-197).
+#
+# Pins the log-only channel's whole contract: one TSV line per ping at the
+# FORGE_SLICE_NOTIFY_LOG path, field-forging bytes scrubbed from caller input,
+# best-effort exit 0 even when the write fails, and the FORGE_SLICE_WORK_DIR
+# default location. Pure fixtures.
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CHAN="$SCRIPT_DIR/../forge-jarvis-notify-logonly.sh"
+[ -f "$CHAN" ] || printf 'NOTE: %s missing — RED phase, every case should FAIL\n' "$CHAN" >&2
+
+ROOT="$(mktemp -d)"
+trap 'rm -rf "$ROOT"' EXIT INT TERM
+
+PASSED=0; FAILED=0
+ok()  { PASSED=$((PASSED+1)); printf '  ok   %s\n' "$1"; }
+bad() { FAILED=$((FAILED+1)); printf '  FAIL %s\n     %s\n' "$1" "$2"; }
+TAB="$(printf '\t')"
+
+# 1. appends exactly one TSV line: ts <TAB> type <TAB> payload
+LOG="$ROOT/notify.log"
+FORGE_SLICE_NOTIFY_LOG="$LOG" sh "$CHAN" ambiguity "JWT or sessions?"; RC=$?
+if [ "$RC" -eq 0 ] && [ "$(wc -l < "$LOG" | tr -d ' ')" = 1 ] \
+   && grep -q "${TAB}ambiguity${TAB}JWT or sessions?$" "$LOG"; then
+  ok 'one ping → one TSV line (ts, type, payload), exit 0'
+else
+  bad 'one ping → one TSV line (ts, type, payload), exit 0' "rc=$RC log=$(cat "$LOG" 2>/dev/null)"
+fi
+
+# 2. a payload with embedded newline/tab cannot forge lines or fields
+FORGE_SLICE_NOTIFY_LOG="$LOG" sh "$CHAN" done "line1
+line2${TAB}forged-field"
+LINES="$(wc -l < "$LOG" | tr -d ' ')"
+FIELDS="$(tail -1 "$LOG" | awk -F"$TAB" '{print NF}')"
+if [ "$LINES" = 2 ] && [ "$FIELDS" = 3 ]; then
+  ok 'newline/tab in payload scrubbed — no forged lines, still 3 TSV fields'
+else
+  bad 'newline/tab in payload scrubbed — no forged lines, still 3 TSV fields' "lines=$LINES fields=$FIELDS"
+fi
+
+# 3. best-effort contract: unwritable log target → still exit 0 (never a slice failure)
+FORGE_SLICE_NOTIFY_LOG="$ROOT/no-perm/notify.log" sh -c 'mkdir -p "'"$ROOT"'/no-perm" && chmod 555 "'"$ROOT"'/no-perm"'
+FORGE_SLICE_NOTIFY_LOG="$ROOT/no-perm/notify.log" sh "$CHAN" done "cannot land"; RC=$?
+chmod 755 "$ROOT/no-perm" 2>/dev/null
+if [ "$RC" -eq 0 ]; then
+  ok 'unwritable log → exit 0 (best-effort, never a slice failure)'
+else
+  bad 'unwritable log → exit 0 (best-effort, never a slice failure)' "rc=$RC"
+fi
+
+# 4. default location: FORGE_SLICE_WORK_DIR/notify.log when NOTIFY_LOG is unset
+WORK="$ROOT/work"; mkdir -p "$WORK"
+( unset FORGE_SLICE_NOTIFY_LOG 2>/dev/null; FORGE_SLICE_WORK_DIR="$WORK" sh "$CHAN" note "hello" )
+if [ -f "$WORK/notify.log" ] && grep -q "${TAB}note${TAB}hello$" "$WORK/notify.log"; then
+  ok 'default location is FORGE_SLICE_WORK_DIR/notify.log'
+else
+  bad 'default location is FORGE_SLICE_WORK_DIR/notify.log' "$(ls "$WORK" 2>/dev/null)"
+fi
+
+printf '\nforge-jarvis-notify-logonly.test.sh: %s passed, %s failed\n' "$PASSED" "$FAILED"
+[ "$FAILED" -eq 0 ]