forge-orkes 0.63.0 → 0.64.2

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

@@ -0,0 +1,109 @@
+#!/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: <git-common-dir>/forge/relay-markers — stable across
+#                          worktrees and cwds; cwd/.relay-markers only outside a repo)
+#   --dry-run              print the resolved plan (pr, repo, env, bound) and exit; no polling
+set -u
+
+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 ;;
+    *) printf 'forge-jarvis-prwatch: unknown argument: %s\n' "$1" >&2; exit 2 ;;
+  esac
+done
+[ -n "$PR" ] || { printf 'forge-jarvis-prwatch: --pr <num> is required\n' >&2; exit 2; }
+# The PR number is carried by a runner `done` ping (semi-trusted log content) and is used
+# in the marker filename and as a gh argument — require a plain number before any use.
+case "$PR" in
+  *[!0-9]*|'') printf 'forge-jarvis-prwatch: --pr must be numeric, got: %s\n' "$PR" >&2; exit 2 ;;
+esac
+# --repo, when given, must be a plain owner/repo — anything else could smuggle gh flags.
+if [ -n "$REPO" ]; then
+  case "$REPO" in
+    */*) case "$REPO" in *[!A-Za-z0-9._/-]*|*/*/*) printf 'forge-jarvis-prwatch: --repo must be owner/repo, got: %s\n' "$REPO" >&2; exit 2 ;; esac ;;
+    *) printf 'forge-jarvis-prwatch: --repo must be owner/repo, got: %s\n' "$REPO" >&2; exit 2 ;;
+  esac
+fi
+# At-most-once marker home: stable per machine+repo (git common dir — shared across this
+# repo's worktrees, never cwd-relative droppings), falling back to cwd only outside a repo.
+if [ -z "$MARKER_DIR" ]; then
+  _cd="$(git rev-parse --git-common-dir 2>/dev/null)"
+  if [ -n "$_cd" ]; then MARKER_DIR="$_cd/forge/relay-markers"; else MARKER_DIR="./.relay-markers"; fi
+fi
+
+if [ "$DRY" = 1 ]; then
+  printf 'prwatch plan: pr=%s repo=%s env=%s bound=%s×%ss marker-dir=%s\n' \
+    "$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)
+  # ${REPO:+…} expands to exactly two argv words when --repo was given, none otherwise.
+  "$GH" pr view "$PR" ${REPO:+--repo "$REPO"} --json state --jq '.state' 2>/dev/null
+}
+deploy_succeeded() { # → exit 0 iff the latest staging deployment is in a success state
+  _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,242 @@
+#!/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)
+#   (gh-based facts live in forge-jarvis-prwatch.sh, which documents its own FORGE_JARVIS_GH;
+#    the board recompute lives in awareness/promote — this helper consults the fold only.)
+#
+# BEST-EFFORT: a fold/gh/board that is absent or errors degrades to release_state=unknown and
+# says so — never a silent success, never a hard fail of the relay path.
+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
+  # Kept textually aligned with fold_state in forge-jarvis-awareness.sh — same guard,
+  # same invocation, same degradation, so a fold-format change is a mechanical two-file edit.
+  _mid="${1:-}"
+  [ -n "$_mid" ] || { printf 'unknown'; return 0; }
+  [ -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'
+}
+
+# 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"
+}
+
+# ── modes — one function per mode, each owning its own arg loop ───────────────────────────────
+MILESTONE=""
+RELAY_MODE="live"          # 'live' | 'catchup' — how --scan emits (not a boolean)
+MARKER_DIR=""
+
+mode_one() {
+  LINE="${1:-}"; shift 2>/dev/null || true
+  while [ $# -gt 0 ]; do case "$1" in
+    --milestone) MILESTONE="${2:-}"; shift 2 ;;
+    *) printf 'forge-jarvis-relay: unknown argument: %s\n' "$1" >&2; exit 2 ;;
+  esac; done
+  relay_one_line "$LINE"; printf '\n'
+  exit 0
+}
+
+mode_list_logs() {
+  # The watch set the skill arms `tail -F` on — recomputed from a DISK GLOB on EVERY call,
+  # never held in memory (Amendment 2: kill Jarvis and the armed watches re-derive from disk).
+  # Live slices are worktrees on a forge/m-* branch; each runner writes to
+  # <worktree>/.forge/runner-work/notify.log (the dispatch's FORGE_SLICE_NOTIFY_LOG). Emit the
+  # EXPECTED path even when the log does not exist yet — `tail -F` (capital F) is chosen exactly
+  # so a not-yet-created log is picked up when the first ping lands (F8).
+  WT_ROOT=""
+  while [ $# -gt 0 ]; do case "$1" in
+    --worktree-root) WT_ROOT="${2:-}"; shift 2 ;;
+    *) printf 'forge-jarvis-relay: unknown argument: %s\n' "$1" >&2; exit 2 ;;
+  esac; done
+  if [ -n "$WT_ROOT" ]; then
+    # override path (tests): disk-glob the given root for slice worktrees.
+    for _wt in "$WT_ROOT"/*/; do
+      [ -d "$_wt" ] || continue
+      printf '%s.forge/runner-work/notify.log\n' "$_wt"
+    done
+  else
+    # live path: `git worktree list` is the on-disk registry of worktrees; glob it to the
+    # forge/m-* slice branches and emit each slice's notify-log path. Pinned with -C so the
+    # watch list never depends on the caller's cwd (the cwd-reset footgun: a snapped cwd
+    # would silently arm ZERO watches).
+    git -C "$REPO_ROOT" worktree list --porcelain 2>/dev/null | awk '
+      /^worktree /  { p=substr($0, 10) }   # full remainder — paths may contain spaces
+      /^branch /    { if ($2 ~ /refs\/heads\/forge\/m-/) print p "/.forge/runner-work/notify.log" }
+    '
+  fi
+  exit 0
+}
+
+mode_audit_sources() {
+  # Static guard: the done/halt (state-claim) branch must recompute from the fold, and the
+  # authoritative release-state var must NEVER be assigned from the payload. Catches a future
+  # rewrite that sources a merge verdict from the session's own payload rather than host truth.
+  # The guard's own two grep lines carry a #@audit tag and are excluded from the scan so their
+  # literal patterns cannot self-match the file they scan.
+  _body="$(grep -vE '#@audit' "$0")"
+  if ! printf '%s\n' "$_body" | grep -qE 'host_release_state|FORGE_JARVIS_FOLD|forge-release-fold'; then  #@audit
+    printf 'forge-jarvis-relay: AUDIT FAIL — no host-truth (fold) recompute in the relay path\n' >&2
+    exit 3
+  fi
+  if printf '%s\n' "$_body" | grep -qE '_rs=["'\''$]*_payload'; then  #@audit
+    printf 'forge-jarvis-relay: AUDIT FAIL — a state claim is sourced from the payload, not the host\n' >&2
+    exit 3
+  fi
+  printf 'relay speaks host truth only\n'
+  exit 0
+}
+
+mode_scan() {
+  LOG="${1:-}"; shift 2>/dev/null || true
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --marker-dir) MARKER_DIR="${2:-}"; shift 2 ;;
+      --milestone)  MILESTONE="${2:-}"; shift 2 ;;
+      --mode)       RELAY_MODE="${2:-live}"; shift 2 ;;
+      *) printf 'forge-jarvis-relay: unknown argument: %s\n' "$1" >&2; exit 2 ;;
+    esac
+  done
+  [ -n "$LOG" ] || { printf 'forge-jarvis-relay: --scan needs a logfile path\n' >&2; exit 2; }
+  # A dispatched-but-not-yet-pinged slice has no log YET — --list-logs deliberately emits
+  # expected paths, so catchup over that set must compose: a missing log is an EMPTY log
+  # (nothing to relay, exit 0), never a refusal. A missing path ARGUMENT stays exit 2 above.
+  [ -f "$LOG" ] || exit 0
+  [ -n "$MARKER_DIR" ] || MARKER_DIR="$(dirname "$LOG")/relay-markers"
+  mkdir -p "$MARKER_DIR" 2>/dev/null || true
+
+  _n=0; _fresh=0; _summary=""
+  # Read every line; relay only those whose offset (line number) has no marker yet.
+  while IFS= read -r _l || [ -n "$_l" ]; do
+    _n=$((_n + 1))
+    _marker="$MARKER_DIR/$_n.relayed"
+    [ -f "$_marker" ] && continue                      # at-most-once: already relayed, never re-buzz
+    _text="$(relay_one_line "$_l")"
+    # Write the marker BEFORE emitting — a crash after emit must not double-buzz; a crash
+    # before emit leaves it unmarked and it re-surfaces as while-you-were-away (no silent loss).
+    # A FAILED marker write must not emit either: emitting unmarked would re-buzz on every
+    # scan (at-most-once silently inverted). Say so loudly and skip — the ping stays unmarked
+    # and re-surfaces once the marker dir is fixed.
+    if ! printf '%s\toffset=%s\t%s\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null || echo now)" "$_n" "$_text" > "$_marker" 2>/dev/null; then
+      printf 'forge-jarvis-relay: WARNING — cannot write marker %s; relay of line %s SUPPRESSED to preserve at-most-once. Fix the marker dir.\n' "$_marker" "$_n" >&2
+      continue
+    fi
+    _fresh=$((_fresh + 1))
+    if [ "$RELAY_MODE" = catchup ]; then
+      _summary="${_summary}${_summary:+ | }$_text"
+    else
+      printf '%s\n' "$_text"                            # live: one relay text per new ping → one buzz
+    fi
+  done < "$LOG"
+
+  if [ "$RELAY_MODE" = catchup ] && [ "$_fresh" -gt 0 ]; then
+    printf '📨 While you were away — %s ping(s): %s\n' "$_fresh" "$_summary"
+  fi
+  # exit 0 whether or not anything was fresh (a no-op scan is success, not failure).
+  exit 0
+}
+
+# ── mode dispatch ─────────────────────────────────────────────────────────────────────────────
+case "${1:-}" in
+  --one)           shift; mode_one "$@" ;;
+  --list-logs)     shift; mode_list_logs "$@" ;;
+  --audit-sources) shift; mode_audit_sources ;;
+  --scan)          shift; mode_scan "$@" ;;
+  *)
+    printf 'usage: forge-jarvis-relay.sh --one "<tsv-line>" [--milestone m-N]\n' >&2
+    printf '       forge-jarvis-relay.sh --scan <logfile> [--marker-dir <dir>] [--milestone m-N] [--mode live|catchup]\n' >&2
+    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,161 @@
+#!/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
+# The resolved name reaches the phone's session list AND the --dry-run line the
+# operator may copy-paste — keep it to a safe, phone-legible charset regardless of
+# where it came from (override flag, config name_suffix, env).
+case "$NAME" in
+  *[!A-Za-z0-9._-]*|'')
+    printf 'forge-jarvis: sticky name must be [A-Za-z0-9._-] only, got: %s\n' "$NAME" >&2; exit 2 ;;
+esac
+
+# --- capacity ----------------------------------------------------------------
+CAP="${CAP_OVERRIDE:-$(jarvis_cfg capacity)}"
+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 -----------------------------------------------------------------
+# The ONE command shape, built once — --dry-run prints exactly the argv launch
+# execs (modulo the caffeinate degradation below), so the two can never drift.
+set -- claude remote-control --name "$NAME" --spawn worktree --capacity "$CAP"
+
+if [ "$DRY_RUN" = "1" ]; then
+  printf 'caffeinate -s %s\n' "$*"
+  exit 0
+fi
+
+# Boot arming (contract B4(a)) is the PRE-CREATED SESSION's act, not the launcher's:
+# the session arms Monitor `tail -F` watches on the live notify logs per
+# .claude/skills/jarvis/SKILL.md ("Session binding" / arm-the-watches). The launcher
+# stays presence-only and deliberately keeps no relay glue.
+
+# --- launch ------------------------------------------------------------------
+command -v claude >/dev/null 2>&1 || {
+  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 "$@"
+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 "$@"
+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 ]