forge-orkes 0.62.0 → 0.64.0

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

@@ -0,0 +1,103 @@
+#!/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 + 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.
+#   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)
+#   FORGE_JARVIS_FOLD   default .claude/hooks/forge-release-fold.sh   (per-unit 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}"
+FOLD="${FORGE_JARVIS_FOLD:-$REPO_ROOT/.claude/hooks/forge-release-fold.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 ;;
+    --*)       shift ;;                          # tolerate/ignore unknown flags
+    *)         [ -z "$SHA" ] && SHA="$1"; shift ;;
+  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
+      printf '%s\n' "$_rel" \
+        | sed -E 's/.*"forge_id":[[:space:]]*"([^"]+)".*"release_state":[[:space:]]*"([^"]+)".*/   \1  release_state=\2/' \
+        | head -60
+    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.
+"$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"

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

@@ -0,0 +1,92 @@
+#!/usr/bin/env sh
+# forge-jarvis-prwatch.sh — the bounded "merged, on staging — come try" watch
+# (m-37, Brief-R2 step 4 B4(c); contract handoff-step4-jarvis.md REV2).
+#
+# The runner's `done` ping fires at PR-open; step-2 auto-merge + the staging deploy land minutes
+# LATER, so that flagship "come try it" moment never appears in the notify log. This watch is the
+# SECOND bounded source for it: on a `done`, poll `gh` for the PR's merge + staging-deploy state
+# with a HARD bound and, on merge+deploy, emit the come-try text once.
+#
+# STRICTLY BOUNDED + self-terminating (NFR-036 / Fork 3): it stops on merge+deploy, on a closed
+# PR, or when the iteration/wall bound is hit — it NEVER becomes a standing daemon and owns no
+# durable state beyond the at-most-once come-try marker (keyed by PR number).
+#
+# HOST TRUTH ONLY: merge + deploy state come from `gh`, never from a build session's words
+# (operator ruling 5). The gh binary is env-overridable (FORGE_JARVIS_GH) so fixtures drive tests.
+#
+#   --pr <num>             the PR to watch (required)
+#   --repo <owner/repo>    default: the current repo (gh resolves it)
+#   --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)
+#   --dry-run              print the resolved plan (pr, repo, env, bound) and exit; no polling
+set -u
+
+PR=""; REPO=""; ENV_STAGING="staging"; MAX_ITER=30; INTERVAL=20; MARKER_DIR=""
+GH="${FORGE_JARVIS_GH:-gh}"
+DRY=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --pr)            PR="${2:-}"; shift 2 ;;
+    --repo)          REPO="${2:-}"; shift 2 ;;
+    --staging-env)   ENV_STAGING="${2:-staging}"; shift 2 ;;
+    --max-iterations) MAX_ITER="${2:-30}"; shift 2 ;;
+    --interval)      INTERVAL="${2:-20}"; shift 2 ;;
+    --marker-dir)    MARKER_DIR="${2:-}"; shift 2 ;;
+    --dry-run)       DRY=1; shift ;;
+    *) shift ;;
+  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"
+
+if [ "$DRY" = 1 ]; then
+  printf 'prwatch plan: pr=%s repo=%s env=%s bound=%s×%ss marker-dir=%s\n' \
+    "$PR" "${REPO:-<current>}" "$ENV_STAGING" "$MAX_ITER" "$INTERVAL" "$MARKER_DIR"
+  exit 0
+fi
+
+# --- host-truth probes (gh only) -------------------------------------------------------------
+# The two probes are literal gh queries (env-overridable via $GH for fixtures):
+#   merge state   → `gh pr view <num> --json state --jq .state`
+#   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
+}
+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
+  _s="$("$GH" api "$_st?per_page=1" --jq '.[0].state' 2>/dev/null)"
+  [ "$_s" = success ]
+}
+
+fire_come_try() {    # at-most-once, keyed by PR (the ONE owned state class)
+  mkdir -p "$MARKER_DIR" 2>/dev/null || true
+  _mk="$MARKER_DIR/pr-$PR-cometry.relayed"
+  [ -f "$_mk" ] && return 0                       # already fired — never re-buzz
+  _text="🚀 Merged, on staging — come try: PR #$PR is live on $ENV_STAGING."
+  printf '%s\toffset=pr-%s\t%s\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null || echo now)" "$PR" "$_text" > "$_mk" 2>/dev/null || true
+  printf '%s\n' "$_text"                           # the skill fires PushNotification with this
+}
+
+# --- the bounded poll loop -------------------------------------------------------------------
+i=0
+while [ "$i" -lt "$MAX_ITER" ]; do
+  case "$(pr_merge_state)" in
+    MERGED)
+      if deploy_succeeded; then fire_come_try; exit 0; fi ;;   # the come-try moment — fire + stop
+    CLOSED)
+      exit 0 ;;                                                # closed without a live deploy — stop, no fire
+    *) : ;;                                                    # OPEN (or gh hiccup) — keep polling
+  esac
+  i=$((i + 1))
+  [ "$i" -lt "$MAX_ITER" ] && [ "$INTERVAL" -gt 0 ] && sleep "$INTERVAL"
+done
+# bound reached without a merge+deploy — self-terminate cleanly, no fire (never a daemon).
+exit 0

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

@@ -0,0 +1,215 @@
+#!/usr/bin/env sh
+# forge-jarvis-relay.sh — the callback-relay CORE (m-37, Brief-R2 step 4 B4(a/b/c/e);
+# contract handoff-step4-jarvis.md REV2). Turns one notify-log line into a relay
+# decision: HOST-TRUTH recompute → typed relay text → at-most-once offset marker.
+#
+# The runner writes every §8 ping to a slice's notify.log (tab-separated
+# `timestamp<TAB>type<TAB>payload`; forge-slice-notify.sh / -notify-logonly.sh). Under a
+# live Jarvis, that log IS the event bus: the skill arms a Monitor `tail -F` on it and pipes
+# each new line through THIS helper, then fires PushNotification with the returned text.
+#
+# THE LOAD-BEARING RULE (operator ruling 5): every relayed STATE claim (merged / landed /
+# validated) is recomputed from HOST truth (the fold / gh / board) BEFORE relay — NEVER taken
+# from the payload. A payload that claims what the host does not show relays the DISCREPANCY,
+# loudly. A question (ambiguity) is relayed verbatim — it is a question, not a state claim.
+#
+# OWNED STATE (the ONE admitted class, NFR-036): durable marker files keyed by the log-line
+# OFFSET (1-based line number — stable in an append-only log; the runner's internal ping-dedup
+# keys never reach the log, F10). Marker present → already relayed → never re-buzz (at-most-once).
+# Everything else Jarvis "knows" is recomputed; kill Jarvis and only the live connection + armed
+# watches are lost — the markers on disk survive and re-drive the while-you-were-away catch-up.
+#
+# MODES
+#   --one   "<tsv-line>" [--milestone m-N]     pure text-builder: print the relay text for ONE
+#                                              line; NO marker, NO side effects (the unit tests hit).
+#   --scan  <logfile> [--marker-dir <dir>] [--milestone m-N] [--mode live|catchup]
+#                                              stateful driver: relay every UNMARKED line, write
+#                                              its marker. live → one text line per new ping;
+#                                              catchup → ONE "while you were away" summary. Both
+#                                              write markers, so a line is relayed at-most-once.
+#   --audit-sources <?logfile>                 self-grep: fail if any state claim is sourced from
+#                                              the payload rather than fold/gh/board (acceptance #3).
+#
+# 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)
+#
+# 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.
+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}"
+
+# ── 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
+  _mid="${1:-}"
+  [ -n "$_mid" ] || { printf 'unknown'; return 0; }
+  _out="$("$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'
+}
+
+# Does the payload TEXT assert a landing/merge/promotion? (only then can it contradict the host)
+payload_claims_landed() {  # payload_claims_landed <payload>
+  printf '%s' "${1:-}" | grep -qiE 'merged|landed|validated|promoted|on main|is live|shipped|deployed'
+}
+
+# ── build the relay text for ONE parsed ping (the pure host-truth text-builder) ───────────────
+# Reads: $2=type $3=payload ; $MILESTONE (optional, for fold). Prints one line to stdout.
+build_relay_text() {  # build_relay_text <type> <payload>
+  _type="${1:-note}"; _payload="${2:-}"
+  case "$_type" in
+    ambiguity)
+      # A QUESTION — relay verbatim, named. Legal: it is not a state claim (acceptance #2).
+      printf '❓ Needs you (ambiguity): %s' "$_payload" ;;
+    fork)
+      # payload is a PATH to a sketch the operator LOOKS AT (§8) — name it.
+      printf '🎨 Design fork — review the sketch: %s' "$_payload" ;;
+    irreversible)
+      # a gate on an irreversible act — your call; relay verbatim, named.
+      printf '⚠️ Irreversible action — your call: %s' "$_payload" ;;
+    budget)
+      # the runner's OWN spend tally — no host source to recompute against; relay verbatim, named.
+      printf '💸 Budget cap reached: %s' "$_payload" ;;
+    done|halt)
+      # STATE-CLAIM territory. Recompute host truth FIRST; build the claim from it, not the payload.
+      _rs="$(host_release_state "${MILESTONE:-}")"
+      if [ "$_type" = done ]; then _base='✅ Slice done'; else _base='🛑 Slice HALTED'; fi
+      if payload_claims_landed "$_payload"; then
+        if [ "$_rs" = unmerged ]; then
+          # The standing lesson: payload says merged, host says not. Relay the host, loudly.
+          printf '⚠️ DISCREPANCY — payload claims landed/merged, but host shows release_state=unmerged. %s (host truth wins). Payload said: %s' "$_base" "$_payload"
+        elif [ "$_rs" = unknown ]; then
+          printf '⚠️ %s — payload claims landed/merged but the host could NOT be verified (release_state=unknown). Payload said: %s' "$_base" "$_payload"
+        else
+          # payload claims landed AND host agrees (merged/validated) — no discrepancy.
+          printf '%s — host confirms: release_state=%s. %s' "$_base" "$_rs" "$_payload"
+        fi
+      else
+        printf '%s — host: release_state=%s. %s' "$_base" "$_rs" "$_payload"
+      fi ;;
+    *)
+      # unknown type — relay raw, named (never silently drop).
+      printf '(%s): %s' "$_type" "$_payload" ;;
+  esac
+}
+
+# Parse a TSV log line (ts<TAB>type<TAB>payload) then build text. Prints one line.
+relay_one_line() {  # relay_one_line <tsv-line>
+  _line="$1"
+  _type="$(printf '%s' "$_line" | cut -f2)"
+  _payload="$(printf '%s' "$_line" | cut -f3-)"
+  # A malformed line with no tabs → cut returns the whole line for f2/f3; treat as a raw note.
+  case "$_line" in
+    *"	"*) : ;;                       # has a tab — well-formed
+    *) _type='note'; _payload="$_line" ;;
+  esac
+  build_relay_text "$_type" "$_payload"
+}
+
+# ── mode dispatch ─────────────────────────────────────────────────────────────────────────────
+MILESTONE=""
+MODE_LIVE="live"
+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 ;;
+
+  --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
+    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
+
+    _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"
+
+    if [ "$MODE_LIVE" = 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 ;;
+
+  *)
+    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
+    printf '       forge-jarvis-relay.sh --list-logs [--worktree-root <dir>]\n' >&2
+    printf '       forge-jarvis-relay.sh --audit-sources\n' >&2
+    exit 2 ;;
+esac

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

@@ -0,0 +1,160 @@
+#!/usr/bin/env sh
+# forge-jarvis.sh — the Jarvis launcher (m-37, Brief-R2 step 4 B2; contract handoff-step4-jarvis.md REV2).
+#
+# Starts the repo's ONE standing front door: a named `claude remote-control` server whose
+# PRE-CREATED session is Jarvis — intake, dispatch, callback relay, awareness (B3-B5 attach
+# to the session this launcher creates; this script is only the presence). Operator-started
+# when he sits down (presence ops v1-minimal, operator-ruled 2026-07-20): no login items,
+# no watchdogs, no daemon. The launcher is STATELESS — killing the server loses only the
+# live connection and armed watches; everything re-establishes at restart from files
+# (Amendment 2; B1 probe viii: dispatched work survives Jarvis's death via nohup-&).
+#
+# RESOLVED COMMAND SHAPE (operator ruling 6, 2026-07-21):
+#   caffeinate -s claude remote-control --name <sticky-name> --spawn worktree --capacity <N>
+#
+#   caffeinate -s     B1 probe (iii): sleep suspends local COMPUTE (dispatches, Monitor-
+#                     triggered autonomous turns, sandbox allocation) while the RC
+#                     connection persists — "present but asleep". -s keeps the machine
+#                     awake on AC POWER ONLY; on battery, normal sleep + queue-until-wake
+#                     apply. One word in the launch command, not nursing machinery.
+#                     (caffeinate absent on PATH → warn + launch unwrapped, portably.)
+#   --name            B1 probe (ii): the phone lists sessions by their first typed message;
+#                     the pre-created session's --name is the ONLY sticky, recognizable
+#                     discoverability anchor. Default: jarvis-<repo-basename>; a per-machine
+#                     suffix names each machine on multi-machine repos (forge:
+#                     jarvis-forge-personal / jarvis-forge-work).
+#   --spawn worktree  on-demand sessions get isolated worktrees (step 0, platform-enforced).
+#                     NOTE (probe ii finding): spawned bridge worktrees live under
+#                     .claude/worktrees/ and do NOT auto-clean — B5 presence-ops owns that.
+#   --capacity        sane for one operator; default 4.
+#
+# AUTH — NO TOKEN EXPORT (B1 probe iv): headless `claude -p` dispatches authenticate via
+# the machine's KEYCHAIN credential with CLAUDE_CODE_OAUTH_TOKEN unset. This launcher must
+# never export a token; if a thinner env ever surfaces the need, `claude setup-token` is
+# the operator's minting path — never committed, never set here.
+#
+# PERMISSIONS — NO FLAGS NEEDED FOR THE PRE-CREATED SESSION (B1 probe vii): typed Bash,
+# Monitor-arm, and PushNotification all run prompt-free in the pre-created session as-is;
+# `--permission-mode` governs only SPAWNED sessions. Nothing to provision here. (Probe vii
+# still owes an explicit check for any OTHER tool a later phase uses unattended.)
+#
+# CONFIG — optional `jarvis:` block in .forge/project.yml (board-block precedent):
+#   jarvis:
+#     enabled: true          # explicit false = this launcher refuses (door switched off)
+#     name_suffix: ""        # appended: jarvis-<repo>-<suffix>; env FORGE_JARVIS_NAME_SUFFIX
+#                            #   overrides per machine (the multi-machine seam)
+#     capacity: 4            # RC server session capacity
+#   NO block → sensible defaults (the launcher is operator-invoked, not ambient — unlike
+#   the board, absence does not mean inert).
+#
+# USAGE:
+#   .forge/checks/forge-jarvis.sh [--dry-run] [--name <full-name>] [--capacity <N>]
+#     --dry-run    print the fully resolved command on stdout and exit 0 — never executes.
+#     --name       full sticky-name override (skips derivation entirely).
+#     --capacity   override config/default capacity.
+#
+# BOUNDARIES (contract "Not this step"): no routing, no approval surface, no new
+# notification infrastructure, no Jarvis-owned state. This script keeps none.
+set -u
+
+# --- args -------------------------------------------------------------------
+DRY_RUN=0
+NAME_OVERRIDE=""
+CAP_OVERRIDE=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --dry-run) DRY_RUN=1; shift ;;
+    --name) shift; NAME_OVERRIDE="${1:-}"; [ $# -gt 0 ] && shift || true ;;
+    --name=*) NAME_OVERRIDE="${1#*=}"; shift ;;
+    --capacity) shift; CAP_OVERRIDE="${1:-}"; [ $# -gt 0 ] && shift || true ;;
+    --capacity=*) CAP_OVERRIDE="${1#*=}"; shift ;;
+    *) printf 'forge-jarvis: unknown argument: %s\n' "$1" >&2; exit 2 ;;
+  esac
+done
+
+# --- repo (refusal, not fallback: --spawn worktree needs a real git repo) ----
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || {
+  printf 'forge-jarvis: not inside a git repo — `claude remote-control --spawn worktree` needs one.\n' >&2
+  exit 2
+}
+PROJECT="$ROOT/.forge/project.yml"
+# Repo identity for the sticky name: the git COMMON dir's parent, not the checkout's
+# toplevel — stable across worktrees (a worktree basename like m-37 must never leak
+# into the phone-visible name). The presence itself belongs on the MAIN checkout
+# (the shape: Jarvis runs on the repo's main checkout in a real terminal).
+COMMON="$(git rev-parse --git-common-dir)"
+REPO_BASE="$(basename "$(cd "$(dirname "$COMMON")" && pwd)")"
+
+# --- config: read a scalar under the top-level `jarvis:` block ---------------
+jarvis_cfg() { # $1 = key under jarvis:
+  [ -f "$PROJECT" ] || return 0
+  awk -v k="$1" '
+    /^jarvis:/ { inb=1; next }
+    inb && /^[A-Za-z]/ { inb=0 }
+    inb && $0 ~ "^[[:space:]]+"k":" {
+      sub(/^[[:space:]]*[^:]+:[[:space:]]*/, "")
+      sub(/[[:space:]]*#.*/, "")
+      gsub(/^["'"'"']|["'"'"']$/, "")
+      print; exit
+    }
+  ' "$PROJECT"
+}
+
+# --- enabled gate (explicit false refuses; absent block = defaults) ----------
+if [ "$(jarvis_cfg enabled)" = "false" ]; then
+  printf 'forge-jarvis: jarvis.enabled is false in .forge/project.yml — the door is switched off.\n' >&2
+  exit 2
+fi
+
+# --- sticky name (probe ii: the only discoverability anchor) -----------------
+if [ -n "$NAME_OVERRIDE" ]; then
+  NAME="$NAME_OVERRIDE"
+else
+  NAME="jarvis-$REPO_BASE"
+  # per-machine seam: env overrides config (multi-machine repos name each machine)
+  SUFFIX="${FORGE_JARVIS_NAME_SUFFIX:-$(jarvis_cfg name_suffix)}"
+  [ -n "$SUFFIX" ] && NAME="$NAME-$SUFFIX"
+fi
+
+# --- capacity ----------------------------------------------------------------
+CAP="${CAP_OVERRIDE:-$(jarvis_cfg capacity)}"
+CAP="${CAP:-4}"
+case "$CAP" in
+  *[!0-9]*|'') printf 'forge-jarvis: capacity must be a positive integer, got: %s\n' "$CAP" >&2; exit 2 ;;
+esac
+
+# --- resolve -----------------------------------------------------------------
+# Printed exactly as executed (modulo the caffeinate degradation below).
+RESOLVED="caffeinate -s claude remote-control --name $NAME --spawn worktree --capacity $CAP"
+
+if [ "$DRY_RUN" = "1" ]; then
+  printf '%s\n' "$RESOLVED"
+  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
+
+# --- launch ------------------------------------------------------------------
+command -v claude >/dev/null 2>&1 || {
+  printf 'forge-jarvis: `claude` not found on PATH.\n' >&2
+  exit 2
+}
+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"
+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"
+fi

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

@@ -0,0 +1,75 @@
+#!/usr/bin/env sh
+# Fixture test suite for .forge/checks/forge-jarvis-answer.sh (m-37, step 4 B4(d); plan 68-02).
+#
+# Contract under test (handoff-step4-jarvis.md REV2 B4(d); NFR-037; acceptance #2):
+#   - the answer lands at the EXACT m-35 path: <work-dir>/phase-<N>/answer.md, with the reply text.
+#   - after writing, the slice is re-dispatched via forge-jarvis-dispatch.sh (stubbed here).
+#   - NEG-CONTROL: no answer content → nothing written, nothing re-dispatched (slice stays parked).
+#   - the reply may arrive via --answer or via stdin.
+#
+# The dispatch is stubbed via FORGE_JARVIS_DISPATCH (records that it was called) so no real runner
+# spawns. Each assertion prints WHY. RED-friendly: a missing script fails every case.
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ANSWER="$SCRIPT_DIR/../forge-jarvis-answer.sh"
+[ -f "$ANSWER" ] || printf 'NOTE: %s missing — RED phase, every case should FAIL\n' "$ANSWER" >&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"; }
+
+# stub dispatch: record the call so we can assert re-dispatch happened (no real runner spawns)
+STUBD="$ROOT/dispatch-stub.sh"
+CALLED="$ROOT/dispatch.called"
+printf '#!/usr/bin/env sh\nprintf "%%s\\n" "$*" > "%s"\n' "$CALLED" > "$STUBD"
+chmod +x "$STUBD"
+SLICE="$ROOT/slice"; mkdir -p "$SLICE"
+
+# 1. answer via --answer → lands at the EXACT m-35 path with the reply text
+WD="$ROOT/w1"; rm -f "$CALLED"
+FORGE_JARVIS_DISPATCH="$STUBD" sh "$ANSWER" --work-dir "$WD" --phase 3 --slice "$SLICE" --answer "Use JWT." >/dev/null 2>&1
+if [ -f "$WD/phase-3/answer.md" ] && grep -q 'Use JWT.' "$WD/phase-3/answer.md"; then
+  ok "answer lands at the EXACT m-35 path <work-dir>/phase-3/answer.md with the reply text"
+else
+  bad "m-35 answer path" "missing or wrong content at $WD/phase-3/answer.md"
+fi
+
+# 2. re-dispatch invoked (the stub recorded the call, carrying --slice + --work-dir)
+if [ -f "$CALLED" ] && grep -q -- "--slice $SLICE" "$CALLED" && grep -q -- "--work-dir $WD" "$CALLED"; then
+  ok "slice re-dispatched after the answer landed (forge-jarvis-dispatch called with --slice/--work-dir)"
+else
+  bad "re-dispatch" "dispatch not called or missing args: $(cat "$CALLED" 2>/dev/null)"
+fi
+
+# 3. NEG-CONTROL: no answer (empty stdin) → nothing written, NO re-dispatch, non-zero exit
+WD2="$ROOT/w2"; rm -f "$CALLED"
+FORGE_JARVIS_DISPATCH="$STUBD" sh "$ANSWER" --work-dir "$WD2" --phase 3 --slice "$SLICE" </dev/null >/dev/null 2>&1; rc=$?
+if [ "$rc" != 0 ] && [ ! -f "$WD2/phase-3/answer.md" ] && [ ! -f "$CALLED" ]; then
+  ok "neg-control: no answer → nothing written, no re-dispatch (slice stays parked), non-zero exit"
+else
+  bad "neg-control no-answer" "rc=$rc wrote=$([ -f "$WD2/phase-3/answer.md" ] && echo yes) dispatched=$([ -f "$CALLED" ] && echo yes)"
+fi
+
+# 4. answer via stdin also works (phone/typed reply piped in)
+WD3="$ROOT/w3"; rm -f "$CALLED"
+printf 'sessions, not JWT' | FORGE_JARVIS_DISPATCH="$STUBD" sh "$ANSWER" --work-dir "$WD3" --phase 7 --slice "$SLICE" >/dev/null 2>&1
+if [ -f "$WD3/phase-7/answer.md" ] && grep -q 'sessions, not JWT' "$WD3/phase-7/answer.md" && [ -f "$CALLED" ]; then
+  ok "answer via stdin lands at phase-7/answer.md and re-dispatches"
+else
+  bad "stdin answer" "missing write or dispatch for stdin path"
+fi
+
+# 5. --dry-run: nothing written, nothing dispatched
+WD4="$ROOT/w4"; rm -f "$CALLED"
+FORGE_JARVIS_DISPATCH="$STUBD" sh "$ANSWER" --work-dir "$WD4" --phase 2 --slice "$SLICE" --answer "x" --dry-run >/dev/null 2>&1
+if [ ! -f "$WD4/phase-2/answer.md" ] && [ ! -f "$CALLED" ]; then
+  ok "--dry-run writes nothing and dispatches nothing"
+else
+  bad "dry-run side effects" "dry-run wrote or dispatched"
+fi
+
+printf '\n%s: %d passed, %d failed\n' "$(basename "$0")" "$PASSED" "$FAILED"
+[ "$FAILED" = 0 ]