forge-orkes 0.63.0 → 0.64.2

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

@@ -0,0 +1,133 @@
+#!/usr/bin/env sh
+# forge-jarvis-bridge-clean.sh — reap orphaned RC bridge worktrees, never touch a live one
+# (m-37 B5; FR-206; B1 probe ii finding).
+#
+# RC on-demand `claude remote-control --spawn worktree` sessions create
+# `.claude/worktrees/bridge-{cse-id}` worktrees that DO NOT auto-remove when the session dies
+# (B1 probe ii). Left alone they accumulate. This reaps the orphans — a bridge worktree with no
+# live session — and NEVER a live one.
+#
+# LIVENESS (best-effort, injectable): a bridge worktree is treated as LIVE (kept) if it has
+# uncommitted changes, OR its git LOCK names a pid whose process is still alive. RC locks every
+# `--spawn worktree` bridge under the persistent server's pid ("locked claude agent bridge-<id>
+# (pid N ...)") — that lock, not filesystem mtime, is the authoritative signal: mtime goes stale
+# while the server is very much alive. A lock whose pid is DEAD is a stale lock → ORPHAN. Only an
+# unlocked / no-pid worktree falls back to mtime freshness (--stale-hours, default 6). Because RC
+# locks every bridge, a confirmed orphan is `git worktree unlock`ed before removal; `git worktree
+# remove` (no --force) still refuses a DIRTY worktree, so unsaved work is protected twice over.
+# Overridable via FORGE_JARVIS_BRIDGE_LIVECHECK (a command given the worktree path; exit 0 = live)
+# for a deterministic test or a site-specific session probe.
+#
+# SCOPE GUARD: only paths whose basename matches bridge-* are ever considered; a non-bridge
+# worktree can never be selected, dry-run or not.
+#
+#   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).
+#     --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)"
+REPO_ROOT="$(cd "$SELF_DIR/../.." && pwd)"
+
+DRY_RUN=0
+STALE_HOURS=6
+WT_ROOT=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --dry-run)         DRY_RUN=1; shift ;;
+    --stale-hours)     STALE_HOURS="${2:-6}"; shift 2 ;;
+    # 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"
+
+# portable dir mtime epoch (BSD then GNU); 0 on failure.
+_mtime() {  # _mtime <path>
+  stat -f %m "$1" 2>/dev/null || stat -c %Y "$1" 2>/dev/null || echo 0
+}
+
+# The pid embedded in a worktree's git LOCK reason, if any. RC locks each bridge with a reason
+# like "claude agent bridge-<id> (pid N start ...)"; that pid is the persistent server that owns
+# the worktree. Empty when the worktree is unlocked or its lock reason carries no pid.
+worktree_lock_pid() {  # worktree_lock_pid <worktree-path>  → prints the pid or nothing
+  _wt="$1"; _b="$(basename "$_wt")"
+  git -C "$_wt" worktree list --porcelain 2>/dev/null | awk -v tgt="$_b" '
+    $1=="worktree" { cur=$2; sub(/.*\//,"",cur) }
+    /^locked/ && cur==tgt && match($0,/pid [0-9]+/) {
+      s=substr($0,RSTART,RLENGTH); sub(/pid /,"",s); print s; exit
+    }'
+}
+
+# default liveness (best-effort): uncommitted work OR a LIVE lock pid → live; a DEAD lock pid
+# (the owning RC server is gone) → orphan; only an unlocked / no-pid worktree falls back to mtime.
+default_livecheck() {  # default_livecheck <worktree-path>  → exit 0 if LIVE
+  _wt="$1"
+  [ -n "$(git -C "$_wt" status --porcelain 2>/dev/null)" ] && return 0   # dirty → live
+  _pid="$(worktree_lock_pid "$_wt")"
+  if [ -n "$_pid" ]; then
+    ps -p "$_pid" >/dev/null 2>&1 && return 0   # lock's server alive → live
+    return 1                                     # lock's server dead → stale lock → orphan
+  fi
+  _now="$(date +%s 2>/dev/null || echo 0)"
+  _mt="$(_mtime "$_wt")"
+  [ "$_mt" -gt 0 ] && [ "$_now" -gt 0 ] && [ $(( (_now - _mt) / 3600 )) -lt "$STALE_HOURS" ] && return 0
+  return 1
+}
+
+is_live() {  # is_live <worktree-path>
+  if [ -n "${FORGE_JARVIS_BRIDGE_LIVECHECK:-}" ]; then
+    $FORGE_JARVIS_BRIDGE_LIVECHECK "$1" >/dev/null 2>&1
+  else
+    default_livecheck "$1"
+  fi
+}
+
+# the repo's MAIN worktree — the safe place to run `git worktree remove` from (first list entry).
+main_wt() {  # main_wt <any-worktree-path>
+  git -C "$1" worktree list --porcelain 2>/dev/null | awk '/^worktree /{print $2; exit}'
+}
+
+if [ ! -d "$WT_ROOT" ]; then
+  printf 'forge-jarvis-bridge-clean: no worktrees root (%s) — nothing to reap.\n' "$WT_ROOT"
+  exit 0
+fi
+
+_kept=0; _cand=0; _reaped=0
+for _wt in "$WT_ROOT"/bridge-*/; do
+  [ -d "$_wt" ] || continue                              # unmatched glob → skip
+  _wt="${_wt%/}"
+  _base="$(basename "$_wt")"
+  case "$_base" in bridge-*) : ;; *) continue ;; esac    # scope guard (belt-and-braces)
+
+  if is_live "$_wt"; then
+    _kept=$((_kept + 1))
+    printf '  keep    %s (live)\n' "$_base"
+    continue
+  fi
+
+  _cand=$((_cand + 1))
+  if [ "$DRY_RUN" -eq 1 ]; then
+    printf '  orphan  %s (candidate — dry-run, not removed)\n' "$_base"
+    continue
+  fi
+
+  _main="$(main_wt "$_wt")"
+  # RC locks every bridge; a confirmed orphan's lock is stale, so unlock before removing.
+  # `remove` (no --force) still refuses a DIRTY worktree, so unsaved work stays protected.
+  git -C "$_main" worktree unlock "$_wt" 2>/dev/null || true
+  if [ -n "$_main" ] && git -C "$_main" worktree remove "$_wt" 2>/dev/null; then
+    _reaped=$((_reaped + 1))
+    printf '  reaped  %s\n' "$_base"
+  else
+    printf '  SKIP    %s (git worktree remove refused — left intact)\n' "$_base"
+  fi
+done
+
+printf 'bridge-clean: %d kept, %d candidate(s), %d reaped%s.\n' \
+  "$_kept" "$_cand" "$_reaped" "$([ "$DRY_RUN" -eq 1 ] && printf ' (dry-run)')"
+exit 0

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

@@ -0,0 +1,198 @@
+#!/usr/bin/env sh
+# forge-jarvis-dispatch.sh --slice <worktree> [runner args...] [--dry-run]
+#   (m-37, Brief-R2 step 4 B3; contract handoff-step4-jarvis.md REV2)
+#
+# On the operator's "go", Jarvis dispatches the slice runner DETACHED so the build
+# survives Jarvis's death (B1 probe viii: nohup-&). This helper owns ONLY the caller-side
+# environment — the runner loop is UNTOUCHED (the "no runner changes" boundary; the runner's
+# swappable seams are used exactly as designed).
+#
+# WHAT IT SETS (and nothing else):
+#   FORGE_SLICE_NOTIFY_LOG  → INTO the slice worktree (<worktree>/.forge/runner-work/notify.log),
+#                             never the invoker's cwd. The default would land the log in the
+#                             MAIN checkout (one shared file, invisible to the worktree glob,
+#                             dirtying step 0's clean-main invariant). This is the path the B4
+#                             relay derives per slice from its worktree glob. (acceptance #5)
+#   FORGE_SLICE_NOTIFY      → the LOG-ONLY channel (forge-jarvis-notify-logonly.sh), so the
+#                             default channel's per-ping headless `claude -p` push stays quiet
+#                             — under a live relay, delivery is the relay's job; a live default
+#                             channel would risk a double-buzz (B1 probe x). Explicit + portable
+#                             (FR-197): true regardless of the ambient auth shape.
+#
+# MODEL MAP — PASSED THROUGH UNTOUCHED (FR-198, boundary "No routing"): the runner reads
+# config.model_by_phase_type from its CONFIG (the step-5 seam — read, not routed). This helper
+# forwards every runner arg (incl. --config) VERBATIM and carries NO model-selection logic. If
+# this dispatch ever starts choosing models, STOP — routing is step 5.
+#
+# All non-flag args are forwarded to the runner unchanged (--slice <worktree>, and optionally
+# --work-dir / --config / --schema / --report-template — whatever the runner accepts). The only
+# arg this helper consumes for itself is --dry-run.
+#
+#   --dry-run   print the exact `nohup env ... runner ...` command + env on stdout and exit 0;
+#               never dispatches. Use it to show the operator what "go" will run.
+#
+# WORK-ORDER MATERIALIZATION (FR-197; walk run 4, 2026-07-22). The runner's contract
+# (consumed, never edited) is <worktree>/slice.yml listing phase names, each resolving to
+# <worktree>/phases/<name>/plan.md — but the Forge intake act writes plans under
+# .forge/phases/milestone-{id}/{phase}-{name}/plan-NN.md, and nothing bridged the two: the
+# observed failure was a clean dispatch whose runner refused instantly ('no slice.yml'), the
+# refusal visible only in dispatch.out — the operator's phone stayed silent. So before the
+# detach this helper MATERIALIZES the work order from the milestone's locked plans (slice.yml
+# in phase order + phases/<name>/plan.md concatenated from that phase's plan-NN.md files), and
+# REFUSES LOUDLY AND SYNCHRONOUSLY when it cannot — the failure surface is this exit code, not
+# a silent phone. An existing slice.yml is honored untouched (a hand-authored work order wins).
+#   --materialize-only   materialize (or refuse) and exit — no dispatch. Test hook + operator tool.
+set -u
+
+SELF_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SELF_DIR/../.." && pwd)"                     # .forge/checks → repo root
+RUNNER="$REPO_ROOT/.claude/hooks/forge-slice-runner.sh"       # the slice runner (consumed, never edited)
+CHANNEL="$SELF_DIR/forge-jarvis-notify-logonly.sh"            # the log-only channel (sibling)
+
+# --- parse args: consume --dry-run; extract --slice; forward everything else verbatim -------
+# POSIX count-guard idiom: shift originals off the front, re-append forwarded args to the back;
+# when the original count hits 0, "$@" holds exactly the forwarded runner args (spaces safe).
+DRY_RUN=0
+MAT_ONLY=0
+WORKTREE=""
+argc=$#
+while [ "$argc" -gt 0 ]; do
+  arg="$1"; shift; argc=$((argc - 1))
+  case "$arg" in
+    --dry-run)
+      DRY_RUN=1 ;;                                   # ours — not forwarded
+    --materialize-only)
+      MAT_ONLY=1 ;;                                  # ours — not forwarded
+    --slice)
+      WORKTREE="${1:-}"; shift; argc=$((argc - 1))
+      set -- "$@" --slice "$WORKTREE" ;;             # forward it too (runner needs it)
+    *)
+      set -- "$@" "$arg" ;;                          # forward verbatim
+  esac
+done
+
+[ -n "$WORKTREE" ] || { printf 'forge-jarvis-dispatch: --slice <worktree> is required\n' >&2; exit 2; }
+[ -d "$WORKTREE" ] || { printf 'forge-jarvis-dispatch: slice worktree not found: %s\n' "$WORKTREE" >&2; exit 2; }
+WORKTREE="$(cd "$WORKTREE" && pwd)"                  # absolutize — the log path must be stable
+
+[ -f "$RUNNER" ]  || { printf 'forge-jarvis-dispatch: runner not found: %s\n' "$RUNNER" >&2; exit 2; }
+[ -f "$CHANNEL" ] || { printf 'forge-jarvis-dispatch: log-only channel not found: %s\n' "$CHANNEL" >&2; exit 2; }
+
+# --- materialize the work order from the milestone's locked plans (FR-197) -------------------
+# slice.yml present → honored untouched. Absent → build it from the single
+# .forge/phases/milestone-*/ dir: one phases/<name>/plan.md per phase subdir (plan-NN.md
+# concatenated in order), slice.yml listing the names numerically. Cannot → REFUSE, exit 2,
+# BEFORE the detach — the caller sees it synchronously and must relay it to the operator.
+materialize_work_order() {
+  if [ -f "$WORKTREE/slice.yml" ]; then
+    printf 'forge-jarvis-dispatch: slice.yml present — using it as-is\n' >&2
+    return 0
+  fi
+  # Prefer the worktree's OWN milestone — .forge/phases/ carries the repo's whole milestone
+  # history (32 dirs on the forge repo), so "the only milestone dir" is a fixture-world
+  # assumption. The Worktree Convention names the branch forge/{anchor} with anchor =
+  # {milestone-id}[-{session}]; derive the id and pick that milestone's dir.
+  _mdir=""
+  _branch="$(git -C "$WORKTREE" branch --show-current 2>/dev/null)"
+  case "$_branch" in
+    forge/m-*)
+      _anchor="${_branch#forge/m-}"                                   # 40 | 40-a1b2c3d4 | R61-002
+      [ -d "$WORKTREE/.forge/phases/milestone-$_anchor" ] && _mdir="$WORKTREE/.forge/phases/milestone-$_anchor"
+      if [ -z "$_mdir" ]; then
+        _short="${_anchor%-*}"                                        # strip one trailing -token (session suffix)
+        [ "$_short" != "$_anchor" ] && [ -d "$WORKTREE/.forge/phases/milestone-$_short" ] && _mdir="$WORKTREE/.forge/phases/milestone-$_short"
+      fi ;;
+  esac
+  # Fallback (non-git fixture dirs / unconventional branches): a SINGLE milestone dir is
+  # unambiguous; several without a branch-derived pick is a refusal, never a guess.
+  if [ -z "$_mdir" ]; then
+    _mdirs=0
+    for _d in "$WORKTREE"/.forge/phases/milestone-*; do
+      [ -d "$_d" ] || continue
+      _mdirs=$((_mdirs + 1)); _mdir="$_d"
+    done
+    if [ "$_mdirs" -eq 0 ]; then
+      printf 'forge-jarvis-dispatch: REFUSED — no slice.yml and no .forge/phases/milestone-*/ plans in %s; nothing to dispatch. Plan the slice first. RELAY this refusal to the operator.\n' "$WORKTREE" >&2
+      return 2
+    fi
+    if [ "$_mdirs" -gt 1 ]; then
+      printf 'forge-jarvis-dispatch: REFUSED — %s milestone plan dirs in %s and no forge/m-* branch to pick by; ambiguous work order. Write slice.yml explicitly. RELAY this refusal to the operator.\n' "$_mdirs" "$WORKTREE" >&2
+      return 2
+    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
+  # 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"
+    _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 <<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
+    return 2
+  fi
+  mv "$_tmp" "$WORKTREE/slice.yml"
+  printf 'forge-jarvis-dispatch: materialized slice.yml (%s phase(s)) from %s\n' "$_count" "${_mdir#"$WORKTREE"/}" >&2
+  return 0
+}
+
+# --- caller-side env (the two seams; nothing else) ------------------------------------------
+LOG="$WORKTREE/.forge/runner-work/notify.log"        # INTO the slice worktree (B4 derives this)
+
+if [ "$DRY_RUN" = "1" ]; then
+  # Side-effect-free: report work-order state to stderr, print the command to stdout.
+  if [ -f "$WORKTREE/slice.yml" ]; then
+    printf 'forge-jarvis-dispatch: (dry-run) slice.yml present — will be used as-is\n' >&2
+  else
+    printf 'forge-jarvis-dispatch: (dry-run) no slice.yml — a real dispatch materializes it from .forge/phases/milestone-*/\n' >&2
+  fi
+  # Print exactly what would run — greppable: worktree-scoped log, log-only channel, nohup, forwarded args.
+  printf 'nohup env FORGE_SLICE_NOTIFY_LOG=%s FORGE_SLICE_NOTIFY=%s %s' "$LOG" "$CHANNEL" "$RUNNER"
+  for a in "$@"; do printf ' %s' "$a"; done
+  printf ' >%s 2>&1 &\n' "$WORKTREE/.forge/runner-work/dispatch.out"
+  exit 0
+fi
+
+if [ "$MAT_ONLY" = "1" ]; then
+  materialize_work_order; exit $?
+fi
+
+materialize_work_order || exit 2
+
+# --- dispatch DETACHED (nohup-& — survives Jarvis's death, B1 probe viii) --------------------
+mkdir -p "$WORKTREE/.forge/runner-work" 2>/dev/null || true
+printf 'forge-jarvis-dispatch: dispatching runner for %s (detached)\n' "$WORKTREE" >&2
+nohup env FORGE_SLICE_NOTIFY_LOG="$LOG" FORGE_SLICE_NOTIFY="$CHANNEL" \
+  "$RUNNER" "$@" >"$WORKTREE/.forge/runner-work/dispatch.out" 2>&1 &
+
+printf 'forge-jarvis-dispatch: dispatched (pid %s); notify log → %s\n' "$!" "$LOG" >&2
+exit 0

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

@@ -0,0 +1,149 @@
+#!/usr/bin/env sh
+# forge-jarvis-instruments.sh — the week's DIRECTION-TEST numbers, derived from what B4 already
+# wrote: the notify logs + relay markers. NO new store (m-37 B5 instruments; FR-205; NFR-036).
+#
+# Risk 1 (contract): did the front door REDUCE operator touches, or just RELOCATE them? These four
+# numbers are how we would tell, measured from existing artifacts ONLY (no instrumentation added):
+#   1. PINGS RELAYED BY TYPE  — how many buzzes, of what kind (ambiguity / fork / irreversible /
+#                               budget / done / halt). Only RELAYED pings count (a marker exists).
+#   2. RELAY LATENCY          — log-line emit-time → marker relay-time, per ping (mean + max secs).
+#   3. DISCREPANCY COUNT      — how often B4(c) host-verification caught a payload's state claim
+#                               disagreeing with the host (the standing lesson, counted).
+#   4. PRESENCE PROXY         — pings relayed LIVE vs pings that landed while the relay was down
+#                               (relayed late, on catch-up). Uptime here is a PROXY derived from
+#                               relay latency, NOT an uptime store: a ping whose relay lagged past
+#                               --live-window seconds is counted "landed while away". Labelled a
+#                               proxy in the output so it is never read as a measured SLA.
+#
+# SOURCES (read-only): each slice's <worktree>/.forge/runner-work/notify.log (TSV
+# emit-ts<TAB>type<TAB>payload) and its sibling relay-markers/<offset>.relayed
+# (relay-ts<TAB>offset=N<TAB>relay-text). A marker's offset (line number) joins it to its log line.
+# Nothing is written; the numbers are a pure function of the existing markers + logs.
+#
+#   forge-jarvis-instruments.sh [--log <notify.log> ...] [--marker-dir <dir>] \
+#                               [--live-window <sec>] [--since <ISO-Z>] [--worktree-root <dir>] [--dry-run]
+#     (no --log)     disk-glob live slice worktrees (git worktree list, forge/m-*) for their logs.
+#     --marker-dir   override the marker dir (default: sibling relay-markers/ of each log).
+#     --live-window  seconds under which a relay counts LIVE (default 120).
+#     --since        only count pings emitted at/after this ISO-Z timestamp (default: all).
+#     --worktree-root  glob this dir for slice worktrees instead of `git worktree list` (tests).
+#     --dry-run      print the resolved logs/markers and exit (plumbing check).
+# Portable date (BSD then GNU) so latency math works on macOS and Linux.
+set -u
+
+SELF_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SELF_DIR/../.." && pwd)"
+
+LOGS=""
+MARKER_DIR_OVERRIDE=""
+LIVE_WINDOW=120
+SINCE=""
+WT_ROOT=""
+DRY_RUN=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --log)           LOGS="${LOGS}${LOGS:+
+}${2:-}"; shift 2 ;;
+    --marker-dir)    MARKER_DIR_OVERRIDE="${2:-}"; shift 2 ;;
+    --live-window)   LIVE_WINDOW="${2:-120}"; shift 2 ;;
+    --since)         SINCE="${2:-}"; shift 2 ;;
+    --worktree-root) WT_ROOT="${2:-}"; shift 2 ;;
+    --dry-run)       DRY_RUN=1; shift ;;
+    *) printf 'forge-jarvis-instruments: unknown argument: %s\n' "$1" >&2; exit 2 ;;
+  esac
+done
+
+# ISO-8601 Z → epoch seconds; empty on failure (GNU `date -d` then BSD `date -j -f`).
+to_epoch() {  # to_epoch <iso-z>
+  _t="${1:-}"; [ -n "$_t" ] || return 1
+  date -u -d "$_t" +%s 2>/dev/null || date -u -j -f '%Y-%m-%dT%H:%M:%SZ' "$_t" +%s 2>/dev/null
+}
+
+# ── resolve the log set: explicit --log wins; else disk-glob live slice worktrees ────────────────
+if [ -z "$LOGS" ]; then
+  if [ -n "$WT_ROOT" ]; then
+    for _wt in "$WT_ROOT"/*/; do
+      [ -d "$_wt" ] || continue
+      _l="${_wt}.forge/runner-work/notify.log"
+      [ -f "$_l" ] && LOGS="${LOGS}${LOGS:+
+}$_l"
+    done
+  else
+    _globbed="$(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" }')"
+    while IFS= read -r _l; do
+      [ -n "$_l" ] || continue
+      [ -f "$_l" ] && LOGS="${LOGS}${LOGS:+
+}$_l"
+    done <<GLOBBED_EOF
+$_globbed
+GLOBBED_EOF
+  fi
+fi
+
+if [ "$DRY_RUN" -eq 1 ]; then
+  printf 'forge-jarvis-instruments (--dry-run): resolved logs:\n'
+  if [ -n "$LOGS" ]; then printf '%s\n' "$LOGS" | sed 's/^/   /'; else printf '   (none)\n'; fi
+  exit 0
+fi
+
+# ── build one record per RELAYED ping: type, latency_sec, live(1/0), discrepancy(1/0) ────────────
+TMP="$(mktemp)"; trap 'rm -f "$TMP"' EXIT INT TERM
+_since_epoch=""; [ -n "$SINCE" ] && _since_epoch="$(to_epoch "$SINCE")"
+
+printf '%s\n' "$LOGS" | while IFS= read -r LOG; do
+  [ -n "$LOG" ] && [ -f "$LOG" ] || continue
+  MK="$MARKER_DIR_OVERRIDE"; [ -n "$MK" ] || MK="$(dirname "$LOG")/relay-markers"
+  _n=0
+  while IFS= read -r _line || [ -n "$_line" ]; do
+    _n=$((_n + 1))
+    _emit="$(printf '%s' "$_line" | cut -f1)"
+    _type="$(printf '%s' "$_line" | cut -f2)"
+    if [ -n "$_since_epoch" ]; then
+      _e="$(to_epoch "$_emit")"
+      { [ -n "$_e" ] && [ "$_e" -lt "$_since_epoch" ]; } && continue
+    fi
+    _marker="$MK/$_n.relayed"
+    [ -f "$_marker" ] || continue                      # only RELAYED pings carry instruments data
+    _relayts="$(cut -f1 "$_marker" 2>/dev/null)"
+    _text="$(cut -f3- "$_marker" 2>/dev/null)"
+    _ee="$(to_epoch "$_emit")"; _re="$(to_epoch "$_relayts")"
+    if [ -n "$_ee" ] && [ -n "$_re" ]; then _lat=$((_re - _ee)); else _lat=-1; fi
+    if [ "$_lat" -ge 0 ] && [ "$_lat" -le "$LIVE_WINDOW" ]; then _live=1; else _live=0; fi
+    case "$_text" in
+      *DISCREPANCY*|*"could NOT be verified"*) _disc=1 ;;
+      *) _disc=0 ;;
+    esac
+    printf '%s\t%s\t%s\t%s\n' "$_type" "$_lat" "$_live" "$_disc" >> "$TMP"
+  done < "$LOG"
+done
+
+# ── emit the four numbers ────────────────────────────────────────────────────────────────────────
+_total="$(wc -l < "$TMP" 2>/dev/null | tr -d ' ')"; [ -n "$_total" ] || _total=0
+
+printf '── Jarvis week-zero instruments  (from relay markers + notify logs) ──\n\n'
+
+printf '1. Pings relayed by type (%s total):\n' "$_total"
+if [ "$_total" -gt 0 ]; then
+  cut -f1 "$TMP" | sort | uniq -c | while read -r _c _t; do
+    printf '     %-14s %s\n' "$_t" "$_c"
+  done
+else
+  printf '     (no relayed pings in range)\n'
+fi
+
+awk -F'\t' -v total="$_total" -v win="$LIVE_WINDOW" '
+  { if ($2 + 0 >= 0) { s += $2; n++; if ($2 + 0 > mx) mx = $2 }
+    live += $3; disc += $4 }
+  END {
+    mean = (n > 0) ? s / n : 0
+    printf "2. Relay latency: mean %.1fs, max %ds (over %d timed ping(s); live window %ds)\n", mean, mx + 0, n + 0, win + 0
+    printf "3. Discrepancies caught (host-verification): %d\n", disc + 0
+    away = total - live
+    up = (total > 0) ? (live * 100.0 / total) : 0
+    printf "4. Presence proxy: %d/%d relayed live (%.0f%%); %d landed while away", live + 0, total + 0, up, away + 0
+    printf "  (proxy — derived from relay latency, not an uptime store)\n"
+  }' "$TMP"
+
+exit 0

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

@@ -0,0 +1,46 @@
+#!/usr/bin/env sh
+# forge-jarvis-notify-logonly.sh <type> <payload> — a LOG-ONLY notify channel for
+# Jarvis-dispatched slices (m-37, Brief-R2 step 4 B3; contract handoff-step4-jarvis.md REV2).
+#
+# The default runner channel (.claude/hooks/forge-slice-notify.sh) does TWO things per
+# ping: (1) append it to the durable log, and (2) a best-effort headless `claude -p`
+# PushNotification micro-call. Under a live Jarvis relay (B4), delivery to the phone is the
+# RELAY's job — the Monitor `tail -F` on this log IS the delivery path. Running the default
+# channel's own push in parallel risks a double-buzz (B1 probe x). So a Jarvis dispatch
+# points FORGE_SLICE_NOTIFY at THIS channel, which does step (1) ONLY.
+#
+# Why an EXPLICIT channel and not just "the keychain box has no exported token so the
+# default is already quiet": that quiet is ambient (it depends on CLAUDE_CODE_OAUTH_TOKEN /
+# ANTHROPIC_API_KEY being unset). On a box where a token IS exported, the default WOULD
+# push and double-buzz. Pointing at this channel makes log-only EXPLICIT and PORTABLE
+# (FR-197) — the relay is the one delivery path regardless of the ambient auth shape.
+#
+# This is the runner's swappable channel seam used exactly as designed: the runner is
+# UNTOUCHED; the caller (forge-jarvis-dispatch.sh) owns the env. The log FORMAT is identical
+# to the default channel (same tab-separated timestamp/type/payload) so the log is uniform
+# whichever channel wrote a line — the relay parses one format.
+#
+# BEST-EFFORT by contract (same as the default channel): exit 0 even if the log write
+# fails — the runner treats a non-zero exit as a best-effort miss, never a slice failure.
+#
+# type/payload: the runner calls `$FORGE_SLICE_NOTIFY <type> <payload>`; the type is one of
+# the §8 surface (ambiguity | irreversible | fork | budget | done) plus `halt`.
+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.
+LOG="${FORGE_SLICE_NOTIFY_LOG:-${FORGE_SLICE_WORK_DIR:-.}/notify.log}"
+mkdir -p "$(dirname "$LOG")" 2>/dev/null || true
+printf '%s\t%s\t%s\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null || echo now)" "$TYPE" "$PAYLOAD" >> "$LOG" 2>/dev/null || true
+
+exit 0

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

@@ -0,0 +1,116 @@
+#!/usr/bin/env sh
+# forge-jarvis-promote.sh — the promotion VOICE (m-37, Brief-R2 step 4 B6; contract
+# 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, 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
+# GitHub's Environment gates (both taps: deploy + mint) until the operator presses there.
+# Triggering is not approving — the approval is not Jarvis's to give (operator ruling 3).
+# There is deliberately NO Environment-approval call anywhere in this file; the neg-control in
+# the test suite greps this file to prove it (an approval path would fail the acceptance test).
+#
+#   forge-jarvis-promote.sh <full-sha> [--dry-run]
+#     <full-sha>   the full 40-hex deploy SHA. The promotion tag is promotion/<full-sha>
+#                  (FROZEN with the operator); a short sha is refused — containment needs the
+#                  full one, and Jarvis never invents or truncates a sha.
+#     --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;
+#                       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.
+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}"
+GH="${FORGE_JARVIS_GH:-gh}"
+WORKFLOW="promote.yml"
+
+SHA=""
+DRY_RUN=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --dry-run) DRY_RUN=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
+
+# ── refuse a missing or non-full sha (Jarvis never invents/truncates a sha) ─────────────────────
+case "$SHA" in
+  "") printf 'forge-jarvis-promote: need a full deploy SHA — usage: forge-jarvis-promote.sh <full-sha> [--dry-run]\n' >&2; exit 2 ;;
+esac
+if ! printf '%s' "$SHA" | grep -qE '^[0-9a-f]{40}$'; then
+  printf 'forge-jarvis-promote: %s is not a full 40-hex SHA. Promotion validates by containment against promotion/<full-sha> — pass the full deploy SHA, not a short one.\n' "$SHA" >&2
+  exit 2
+fi
+
+# ── 1. SHOW what this SHA carries — host truth, recomputed now (never a session's claim) ─────────
+printf '── Promote %s ────────────────────────────────────\n' "$SHA"
+printf '\n> What this promotion covers  (board projection — merged units validate by containment):\n'
+if [ -f "$BOARD" ]; then
+  _emit="$(sh "$BOARD" --emit 2>/dev/null)"
+  if [ -n "$_emit" ]; then
+    # release-relevant units: merged (candidate -> validated) + validated (already covered).
+    # 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
+      # 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
+  else
+    printf '   (board projection unavailable — degraded, not fatal)\n'
+  fi
+else
+  printf '   (forge-board-render.sh not found — projection unavailable)\n'
+fi
+printf '\n  Validation is by CONTAINMENT: each merged unit becomes validated when its landed SHA is an\n'
+printf '  ancestor of the signed promotion/%s tag commit (ADR-024) — host-verified offline, not a claim.\n' "$SHA"
+
+# ── 2. TRIGGER the step-2 seam — and STOP. Jarvis triggers; the operator presses the gates. ──────
+CMD="$GH workflow run $WORKFLOW -f sha=$SHA"
+printf '\n> Trigger (step-2 seam — Jarvis triggers; the operator presses GitHub Environment gates):\n'
+if [ "$DRY_RUN" -eq 1 ]; then
+  printf '   [--dry-run] would run: %s\n' "$CMD"
+  exit 0
+fi
+if ! command -v "$GH" >/dev/null 2>&1; then
+  printf '   gh not found — cannot trigger the promotion. Run it from a host that has gh: %s\n' "$CMD" >&2
+  exit 3
+fi
+printf '   %s\n' "$CMD"
+# gh workflow run promote.yml -f sha=<full-sha> — the trigger, never an approval call.
+# 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"
+else
+  printf '\n[!] gh workflow run exited %s — the promotion was NOT triggered. Check the workflow name / host auth.\n' "$_rc" >&2
+fi
+exit "$_rc"