forge-orkes 0.62.0 → 0.64.0

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

@@ -0,0 +1,128 @@
+#!/usr/bin/env sh
+# forge-jarvis-awareness.sh — "what's in play?" answered LIVE, never remembered (m-37,
+# Brief-R2 step 4 B5 awareness; contract handoff-step4-jarvis.md REV2; FR-203/204; NFR-036).
+#
+# The operator asks Jarvis "what's in play?" and every fact in the answer is COMPUTED from a
+# live host source at ask-time — there is no Jarvis-owned status store (NFR-036 / pain 4: the
+# drift class). Three live sources, three questions:
+#   1. WHICH SLICES ARE RUNNING (this machine) → a DISK GLOB of git worktrees on forge/m-*
+#      branches (`git worktree list`), NOT the RC session listing (which is blind to detached
+#      `claude -p` workers — B1 probe ix). Parked/dispatched slices are worktrees on disk, so a
+#      glob sees them; the session listing does not.
+#   2. WHERE EACH SLICE STANDS (cross-machine) → the fold (forge-release-fold.sh m-N) per slice:
+#      unmerged | merged | validated — git-derived, identical on any clone.
+#   3. THE BOARD PROJECTION (cross-machine)     → forge-board-render.sh --emit: the rollup's view
+#      of every unit, offline + deterministic.
+#
+# PER-MACHINE SCOPE (F11 — stated plainly in the output): the disk glob is THIS machine's live/
+# parked slices only; forge is a two-machine repo, so the other machine's in-flight worktrees are
+# invisible here. The git-synced board + fold ARE the cross-machine truth; the glob is the local
+# "what's spinning right now" layer. The answer says so, so a quiet glob is never mistaken for
+# "nothing in flight anywhere".
+#
+# NO OWNED STATE: nothing here is persisted; the next ask recomputes from disk + git. The only
+# durable Jarvis state anywhere is B4's relay markers (a different helper).
+#
+#   forge-jarvis-awareness.sh [--dry-run] [--worktree-root <dir>]
+#     --dry-run          resolve + print structure without shelling to the fold/board (fast
+#                        plumbing check); tests and quick sanity checks use it.
+#     --worktree-root    override the worktree scan root (tests); default: real `git worktree list`.
+#
+# Host-truth commands are env-overridable so tests inject stubs and degradation is explicit:
+#   FORGE_JARVIS_FOLD   default .claude/hooks/forge-release-fold.sh
+#   FORGE_JARVIS_BOARD  default .forge/checks/forge-board-render.sh
+# BEST-EFFORT: a missing fold/board degrades to a stated 'unknown' / '(unavailable)', never a hard
+# fail — the awareness answer always renders.
+set -u
+
+SELF_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SELF_DIR/../.." && pwd)"                 # .forge/checks → repo root
+FOLD="${FORGE_JARVIS_FOLD:-$REPO_ROOT/.claude/hooks/forge-release-fold.sh}"
+BOARD="${FORGE_JARVIS_BOARD:-$REPO_ROOT/.forge/checks/forge-board-render.sh}"
+TAB="$(printf '\t')"
+
+DRY_RUN=0
+WT_ROOT=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --dry-run)       DRY_RUN=1; shift ;;
+    --worktree-root) WT_ROOT="${2:-}"; shift 2 ;;
+    *) shift ;;
+  esac
+done
+
+# ── host truth: a slice's release_state from the fold (never remembered). Degrades to 'unknown'. ─
+fold_state() {  # fold_state <milestone-id>
+  _mid="${1:-}"
+  [ -n "$_mid" ] || { 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'
+}
+
+# ── 1. live/parked slices — a DISK GLOB of worktrees on forge/m-* branches. Same on-disk registry
+#       the relay's --list-logs arms tail -F on; recomputed here, never stored. Emits TSV:
+#       <milestone-id>\t<branch>\t<path>. --worktree-root globs a given dir instead (tests). ──────
+list_slices() {
+  if [ -n "$WT_ROOT" ]; then
+    for _wt in "$WT_ROOT"/*/; do
+      [ -d "$_wt" ] || continue
+      _b="$(basename "$_wt")"
+      printf '%s%s(root-scan)%s%s\n' "$_b" "$TAB" "$TAB" "${_wt%/}"
+    done
+  else
+    git -C "$REPO_ROOT" worktree list --porcelain 2>/dev/null | awk -v tab="$TAB" '
+      /^worktree / { p = $2 }
+      /^branch /   {
+        if ($2 ~ /refs\/heads\/forge\/m-/) {
+          b = $2; sub(/refs\/heads\//, "", b)          # forge/m-37[-<session>]
+          m = b; sub(/^forge\//, "", m); sub(/-[0-9a-f]{8}$/, "", m)   # → m-37
+          print m tab b tab p
+        }
+      }'
+  fi
+}
+
+# ── render ──────────────────────────────────────────────────────────────────────────────────────
+printf '── What'\''s in play?  (host-verified, computed live) ──────────────────\n'
+
+printf '\n▸ Live / parked slices on THIS machine  (git worktree glob):\n'
+_slices="$(list_slices)"
+if [ -n "$_slices" ]; then
+  printf '%s\n' "$_slices" | while IFS="$TAB" read -r _m _br _pt; do
+    if [ "$DRY_RUN" -eq 1 ]; then _rs='(dry-run)'; else _rs="$(fold_state "$_m")"; fi
+    printf '   %-10s  %-26s  release_state=%-9s  %s\n' "$_m" "$_br" "$_rs" "$_pt"
+  done
+else
+  printf '   (none on this machine)\n'
+fi
+
+printf '\n▸ Board projection  (git-synced — cross-machine truth):\n'
+if [ "$DRY_RUN" -eq 1 ]; then
+  printf '   (--dry-run: forge-board-render.sh --emit not invoked)\n'
+elif [ -f "$BOARD" ]; then
+  _emit="$(sh "$BOARD" --emit 2>/dev/null)"
+  if [ -n "$_emit" ]; then
+    # In-flight is what's "in play": one line per non-complete unit. Line-oriented JSON → grep/sed,
+    # 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
+    else
+      printf '   (all board units complete — nothing in flight)\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 '\nScope: the slice list above is PER-MACHINE (this machine'\''s worktrees only).\n'
+printf 'On this two-machine repo the git-synced board + fold are the cross-machine truth;\n'
+printf 'a quiet slice list here does not mean nothing is in flight on the other machine.\n'
+
+exit 0

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

@@ -0,0 +1,130 @@
+#!/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).
+#     --worktrees-root   override the scan root (tests); default: <repo>/.claude/worktrees.
+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 ;;
+    --worktrees-root)  WT_ROOT="${2:-}"; shift 2 ;;
+    *) shift ;;
+  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,176 @@
+#!/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"
+  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
+    mkdir -p "$WORKTREE/phases/$_p"
+    # shellcheck disable=SC2086
+    cat $_plans > "$WORKTREE/phases/$_p/plan.md"
+    printf '  - %s\n' "$_p" >> "$_tmp"
+    _count=$((_count + 1))
+  done
+  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,146 @@
+#!/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 ;;
+    *) shift ;;
+  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 = $2 }
+      /^branch /   { if ($2 ~ /refs\/heads\/forge\/m-/) print p "/.forge/runner-work/notify.log" }')"
+    for _l in $_globbed; do
+      [ -f "$_l" ] && LOGS="${LOGS}${LOGS:+
+}$_l"
+    done
+  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,40 @@
+#!/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:-}"
+
+# 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