@rulemetric/hooks 0.6.9 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulemetric/hooks",
-  "version": "0.6.9",
+  "version": "0.7.0",
   "publishConfig": {
     "access": "public"
   },

package/scripts/_config.sh

@@ -14,7 +14,19 @@ _rulemetric_config_dir() {
     printf '%s' "$RULEMETRIC_CONFIG_DIR"
     return
   fi
-  printf '%s' "${XDG_CONFIG_HOME:-$HOME/.config}/rulemetric"
+  # XDG-aware, BUT the writers (`rulemetric auth login`, the Python reporter)
+  # always use ~/.config/rulemetric. On a Linux host with XDG_CONFIG_HOME set
+  # somewhere else, honoring XDG alone means the hooks look where login never
+  # wrote — no credentials, capture silently dead. Prefer the XDG dir only if
+  # it actually holds a config artifact; otherwise fall back to where the CLI
+  # writes.
+  local xdg_dir="${XDG_CONFIG_HOME:-$HOME/.config}/rulemetric"
+  local default_dir="$HOME/.config/rulemetric"
+  if [ "$xdg_dir" != "$default_dir" ] && [ ! -e "$xdg_dir/env" ] && [ ! -e "$xdg_dir/auth.json" ] && [ -d "$default_dir" ]; then
+    printf '%s' "$default_dir"
+    return
+  fi
+  printf '%s' "$xdg_dir"
 }
 
 # Resolve the active org ID into RULEMETRIC_ORG_ID. Env beats file. A missing
@@ -62,7 +74,12 @@ _rulemetric_load_config() {
     # shellcheck source=/dev/null
     source "$config_dir/env"
     set +a
-    if [ -n "${RULEMETRIC_API_URL:-}" ] && { [ -n "${RULEMETRIC_API_KEY:-}" ] || [ -n "${RULEMETRIC_ACCESS_TOKEN:-}" ]; }; then
+    if [ -n "${RULEMETRIC_API_KEY:-}" ] || [ -n "${RULEMETRIC_ACCESS_TOKEN:-}" ]; then
+      # Credentials are enough — default the API URL like the auth.json branch
+      # below. `auth login` against prod doesn't persist RULEMETRIC_API_URL, so
+      # requiring it here made every fresh npm install skip capture with
+      # "no_config" unless auth.json happened to survive.
+      export RULEMETRIC_API_URL="${RULEMETRIC_API_URL:-https://rulemetric.com}"
       _rulemetric_load_active_org
       return 0
     fi

package/scripts/_ensure-session.sh

@@ -159,14 +159,27 @@ _rulemetric_ensure_session() {
     --argjson runId "$run_id_arg" \
     '{tool: $tool, externalSessionId: $externalSessionId, projectPath: $projectPath, gitBranch: $gitBranch, metadata: $metadata, orgId: $orgId, runId: $runId}')
 
-  local response
-  response=$(curl -sf --noproxy '*' --max-time 4 -X POST "${RULEMETRIC_API_URL}/api/sessions" \
-    -H "$AUTH_HEADER" \
-    -H "Content-Type: application/json" \
-    -d "$payload" \
-    2>/dev/null)
+  # Retry transient failures (503/429/network) instead of the old bare `curl -sf`,
+  # which silently dropped the whole session — and every event that would have
+  # attached to it — on a single transient 502/503 during a load window. Uses the
+  # shared bounded-retry helper (echoes the 2xx body so we can read .id). Callers
+  # normally source _post.sh already; source it defensively if not.
+  if ! command -v _rulemetric_send_capture >/dev/null 2>&1; then
+    _RM_ES_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    # shellcheck source=/dev/null
+    . "$_RM_ES_DIR/_post.sh" 2>/dev/null || true
+  fi
 
-  if [ "$?" -ne 0 ]; then
+  local response
+  response=$(_rulemetric_send_capture POST "${RULEMETRIC_API_URL}/api/sessions" \
+    "$AUTH_HEADER" "$payload" "${1:-ensure-session}" 4)
+
+  if [ "$?" -ne 0 ] || [ -z "$response" ]; then
+    # No local log here — the caller's "skip no_rw_session" must stay the FIRST
+    # entry for its script (hooks.test.ts codifies that contract; an extra line
+    # here mis-classified the benign skip TWICE now). Remote forensics come from
+    # the availability beacon the capture helper fires (statusCode, server-side);
+    # local deep-debug remains via RULEMETRIC_HOOK_DEBUG.
     rmdir "$lock_dir" 2>/dev/null
     return 1
   fi

package/scripts/_normalize.sh

@@ -15,6 +15,21 @@
 #   HOOK_TOOL_OUTPUT - Tool output as JSON
 #   HOOK_TRANSCRIPT_PATH - Path to transcript file (empty if unavailable)
 
+# Portable short content hash for synthetic session IDs. `shasum` is a perl
+# script — absent on minimal Linux hosts (containers, slim distros), where its
+# failure under `set -euo pipefail` killed Cursor/Copilot-CLI capture entirely.
+# Prefer coreutils sha256sum (ubiquitous on Linux), then shasum (macOS), then
+# cksum (POSIX — weaker, but the IDs only need stable uniqueness per input).
+_rulemetric_short_hash() {
+  if command -v sha256sum >/dev/null 2>&1; then
+    printf '%s' "$1" | sha256sum | cut -c1-16
+  elif command -v shasum >/dev/null 2>&1; then
+    printf '%s' "$1" | shasum -a 256 | cut -c1-16
+  else
+    printf '%s' "$1" | cksum | tr -d ' \t' | cut -c1-16
+  fi
+}
+
 _rulemetric_normalize() {
   local input="$1"
 

package/scripts/_post.sh

@@ -18,6 +18,44 @@
 _RM_POST_MAX_ATTEMPTS="${RULEMETRIC_POST_MAX_ATTEMPTS:-3}"
 _RM_POST_RETRY_CAP_S="${RULEMETRIC_POST_RETRY_CAP_S:-2}"
 
+# _rulemetric_beacon <tag> <http_code>
+# Best-effort UNAUTHENTICATED availability beacon (POST /api/telemetry/cli-error,
+# sent DIRECT with --noproxy — a broken local gateway is a prime cause of the
+# failures this reports, so routing through it would suppress the signal). The
+# hooks are the always-on capture component with NO other server-visible failure
+# channel: when their sends exhaust retries, the only trace used to be a line in
+# $TMPDIR — invisible for a remote device. Only availability classes beacon
+# (5xx / network 000 / 408 / 429-exhausted); other 4xx is a rejection, not an
+# outage. Rate-limited to once per hour per tag via a marker file (failures come
+# in storms; one beacon per storm is the signal). Honors the telemetry opt-outs.
+# Fire-and-forget: backgrounded, 2s bound, never fails the caller.
+_rulemetric_beacon() {
+  local tag="$1" code="$2"
+  case "$code" in
+    5??|000|408|429) ;;
+    *) return 0 ;;
+  esac
+  [ "${RULEMETRIC_NO_TELEMETRY:-0}" != "0" ] && return 0
+  [ "${DO_NOT_TRACK:-0}" != "0" ] && return 0
+  local marker_dir="${TMPDIR:-/tmp}/rulemetric" marker now mtime
+  marker="$marker_dir/beacon.$tag"
+  mkdir -p "$marker_dir" 2>/dev/null || return 0
+  if [ -f "$marker" ]; then
+    now=$(date +%s 2>/dev/null || echo 0)
+    mtime=$(stat -f %m "$marker" 2>/dev/null || stat -c %Y "$marker" 2>/dev/null || echo 0)
+    [ $((now - mtime)) -lt 3600 ] && return 0
+  fi
+  : > "$marker" 2>/dev/null || true
+  local code_int proxied
+  code_int=$((10#$code)) 2>/dev/null || code_int=0
+  proxied=$([ -n "${HTTPS_PROXY:-}" ] && echo true || echo false)
+  ( curl -s --noproxy '*' --max-time 2 -X POST \
+      "${RULEMETRIC_API_URL:-https://rulemetric.com}/api/telemetry/cli-error" \
+      -H 'Content-Type: application/json' \
+      --data-binary "{\"event\":\"hook_capture_failed\",\"command\":\"hooks:${tag}\",\"statusCode\":${code_int},\"proxied\":${proxied}}" \
+      > /dev/null 2>&1 || true ) &
+}
+
 # _rulemetric_post_event <url> <auth_header> <payload> <log_tag> <seq>
 # Returns 0 on 2xx; 1 otherwise (after logging the final failure).
 _rulemetric_post_event() {
@@ -30,11 +68,11 @@ _rulemetric_post_event() {
     if [ -n "$hdr_file" ]; then
       body=$(curl -s --noproxy '*' --max-time 4 -D "$hdr_file" -w '\n%{http_code}' \
         -X POST "$url" -H "$auth" -H "Content-Type: application/json" \
-        -d "$payload" 2>&1) || true
+        --data-binary "$payload" 2>&1) || true
     else
       body=$(curl -s --noproxy '*' --max-time 4 -w '\n%{http_code}' \
         -X POST "$url" -H "$auth" -H "Content-Type: application/json" \
-        -d "$payload" 2>&1) || true
+        --data-binary "$payload" 2>&1) || true
     fi
     http_code=$(printf '%s' "$body" | tail -1)
     body=$(printf '%s' "$body" | sed '$d')
@@ -73,6 +111,7 @@ _rulemetric_post_event() {
   done
 
   _rulemetric_log "$tag" "error" "http_${http_code}_seq_${seq}_attempt_${attempt}: ${body}"
+  _rulemetric_beacon "$tag" "$http_code"
   [ -n "$hdr_file" ] && rm -f "$hdr_file"
   return 1
 }
@@ -94,14 +133,20 @@ _rulemetric_send() {
   hdr_file=$(mktemp "${TMPDIR:-/tmp}/rm-send.XXXXXX" 2>/dev/null || true)
 
   while [ "$attempt" -le "$max_attempts" ]; do
+    # --data-binary (not -d) so a payload of "@/path/to/file" streams the body
+    # FROM that file verbatim. Large bodies (session-end reimport can carry a
+    # multi-MB transcript) MUST go via @file: an inline argv element that big
+    # exceeds the kernel's per-arg exec limit and curl never even starts (E2BIG)
+    # — which silently dropped every long session's reimport. Inline JSON
+    # payloads (always starting "{") behave identically under --data-binary.
     if [ -n "$hdr_file" ]; then
       body=$(curl -s --noproxy '*' --max-time "$max_time" -D "$hdr_file" -w '\n%{http_code}' \
         -X "$method" "$url" -H "$auth" -H "Content-Type: application/json" \
-        -d "$payload" 2>&1) || true
+        --data-binary "$payload" 2>&1) || true
     else
       body=$(curl -s --noproxy '*' --max-time "$max_time" -w '\n%{http_code}' \
         -X "$method" "$url" -H "$auth" -H "Content-Type: application/json" \
-        -d "$payload" 2>&1) || true
+        --data-binary "$payload" 2>&1) || true
     fi
     http_code=$(printf '%s' "$body" | tail -1)
     body=$(printf '%s' "$body" | sed '$d')
@@ -138,6 +183,85 @@ _rulemetric_send() {
   done
 
   _rulemetric_log "$tag" "error" "http_${http_code}_attempt_${attempt}: ${body}"
+  _rulemetric_beacon "$tag" "$http_code"
+  [ -n "$hdr_file" ] && rm -f "$hdr_file"
+  return 1
+}
+
+# _rulemetric_send_capture <method> <url> <auth> <payload> <log_tag> [max_time_s] [max_attempts]
+# Like _rulemetric_send, but ECHOES the 2xx response body to stdout so callers
+# that must READ the response can. Its reason to exist: lazy session-create
+# (_ensure-session.sh) needs the new session's `.id` from the response body, and
+# previously used a bare `curl -sf` with NO retry — so a transient 503/429/502
+# during the incident window silently dropped the whole session, and with it every
+# event that would have attached to it (the session row never existed). This gives
+# session-create the SAME bounded 503/429/network retry + capped Retry-After as the
+# event path. 4xx is permanent (no retry). Returns 0 on 2xx (body on stdout); 1
+# otherwise (nothing on stdout). Stays SILENT on failure — the caller inspects
+# the return value and logs its own outcome (e.g. session-create → skip).
+_rulemetric_send_capture() {
+  local method="$1" url="$2" auth="$3" payload="$4" tag="$5" max_time="${6:-4}" max_attempts="${7:-$_RM_POST_MAX_ATTEMPTS}"
+  local attempt=1 http_code="000" body="" hdr_file retry_after sleep_s
+  _RM_CAPTURE_LAST_CODE=""
+
+  hdr_file=$(mktemp "${TMPDIR:-/tmp}/rm-cap.XXXXXX" 2>/dev/null || true)
+
+  while [ "$attempt" -le "$max_attempts" ]; do
+    if [ -n "$hdr_file" ]; then
+      body=$(curl -s --noproxy '*' --max-time "$max_time" -D "$hdr_file" -w '\n%{http_code}' \
+        -X "$method" "$url" -H "$auth" -H "Content-Type: application/json" \
+        --data-binary "$payload" 2>&1) || true
+    else
+      body=$(curl -s --noproxy '*' --max-time "$max_time" -w '\n%{http_code}' \
+        -X "$method" "$url" -H "$auth" -H "Content-Type: application/json" \
+        --data-binary "$payload" 2>&1) || true
+    fi
+    http_code=$(printf '%s' "$body" | tail -1)
+    body=$(printf '%s' "$body" | sed '$d')
+
+    case "$http_code" in 2??)
+      printf '%s' "$body"   # give the caller the response (e.g. to read .id)
+      [ -n "$hdr_file" ] && rm -f "$hdr_file"
+      return 0
+      ;;
+    esac
+
+    if [ "$http_code" = "503" ] || [ "$http_code" = "429" ] || [ "$http_code" = "000" ]; then
+      if [ "$attempt" -lt "$max_attempts" ]; then
+        retry_after=""
+        if [ -n "$hdr_file" ]; then
+          retry_after=$(grep -i '^Retry-After:' "$hdr_file" 2>/dev/null | tail -1 | tr -dc '0-9' || true)
+        fi
+        if [ -n "$retry_after" ] && [ "$retry_after" -gt 0 ] 2>/dev/null; then
+          sleep_s="$retry_after"
+        else
+          sleep_s="$attempt"
+        fi
+        if [ "$sleep_s" -gt "$_RM_POST_RETRY_CAP_S" ] 2>/dev/null; then
+          sleep_s="$_RM_POST_RETRY_CAP_S"
+        fi
+        sleep "$sleep_s" 2>/dev/null || true
+        attempt=$((attempt + 1))
+        continue
+      fi
+    fi
+
+    break
+  done
+
+  # Unlike _rulemetric_send / _rulemetric_post_event (fire-and-forget writes whose
+  # ONLY failure signal is this log line), _rulemetric_send_capture's caller
+  # inspects the return value and logs its OWN outcome — session-create logs
+  # skip/no_rw_session when the API is unreachable (see _ensure-session.sh →
+  # user-prompt.sh). Logging an "error" here too would prepend a second log entry
+  # and mis-classify that benign skip as an error (regressed hooks.test.ts). So
+  # the helper stays SILENT on failure; the caller owns the outcome — the final
+  # HTTP code is exported in _RM_CAPTURE_LAST_CODE so the caller's log can carry
+  # the forensics (a bare "no_rw_session" is undiagnosable from a remote device).
+  # The beacon is server-side, not a log entry, so it doesn't break the contract.
+  # Deep-debug via RULEMETRIC_HOOK_DEBUG remains available on the caller side.
+  _RM_CAPTURE_LAST_CODE="$http_code"
+  _rulemetric_beacon "$tag" "$http_code"
   [ -n "$hdr_file" ] && rm -f "$hdr_file"
   return 1
 }

package/scripts/post-retry.test.sh

@@ -31,8 +31,8 @@ trap cleanup EXIT
 
 # --- Stub server: counts requests, programmed by $MODE in a control file --------
 cat > "$WORK_ROOT/stub.py" <<'PY'
-import http.server, json, os, sys, threading
-mode = sys.argv[1]            # fail-once | always-503 | always-400 | always-202
+import hashlib, http.server, json, os, sys, threading
+mode = sys.argv[1]            # fail-once | always-503 | always-400 | always-202 | echo-len
 count_file = sys.argv[2]
 n = 0
 lock = threading.Lock()
@@ -44,7 +44,10 @@ class H(http.server.BaseHTTPRequestHandler):
             n += 1; cur = n
             open(count_file, "w").write(str(n))
         length = int(self.headers.get('Content-Length', 0) or 0)
-        self.rfile.read(length)
+        body = self.rfile.read(length)
+        if mode == "echo-len":
+            resp = json.dumps({"len": len(body), "sha": hashlib.sha256(body).hexdigest()})
+            self.send_response(200); self.end_headers(); self.wfile.write(resp.encode()); return
         if mode == "always-400":
             self.send_response(400); self.end_headers(); self.wfile.write(b'{"error":"bad"}'); return
         if mode == "always-503":
@@ -80,6 +83,10 @@ LOG_FILE="$WORK_ROOT/log"
 _rulemetric_log() { echo "$*" >> "$LOG_FILE"; }   # stub: record log calls
 export RULEMETRIC_POST_MAX_ATTEMPTS=3
 export RULEMETRIC_POST_RETRY_CAP_S=1
+# The failure paths fire an availability beacon at $RULEMETRIC_API_URL — which
+# in these tests is the counting stub server. Disable telemetry so the beacon
+# can't inflate req_count (it's async, which would also make counts racy).
+export RULEMETRIC_NO_TELEMETRY=1
 # shellcheck source=/dev/null
 source "$SCRIPT_DIR/_post.sh"
 
@@ -127,6 +134,64 @@ assert_eq "always-202: server saw exactly 1 request (no retry)" "1" "$(req_count
 assert_eq "always-202: no error logged" "0" "$(wc -l < "$LOG_FILE" | tr -d ' ')"
 stop_server
 
+# --- Test 5: _rulemetric_send_capture retries a transient 503 AND returns body -
+# Session-create (lazy recovery) uses this to survive a transient 503/502 that
+# previously dropped the whole session. It must retry AND hand back the 2xx body
+# so the caller can read the new session's .id.
+start_server fail-once
+: > "$LOG_FILE"
+cap_body=$(_rulemetric_send_capture POST "http://127.0.0.1:$SERVER_PORT/api/sessions" "$AUTH" "$PAYLOAD" "test" 4)
+rc=$?
+assert_eq "capture/fail-once: returns success (0) after retry" "0" "$rc"
+assert_eq "capture/fail-once: server saw exactly 2 requests (fail + retry)" "2" "$(req_count)"
+assert_eq "capture/fail-once: echoes the 2xx body for the caller to parse .id" '{"recorded":true}' "$cap_body"
+stop_server
+
+# --- Test 6: _rulemetric_send_capture gives up on sustained 503, empty stdout --
+start_server always-503
+: > "$LOG_FILE"
+cap_body=$(_rulemetric_send_capture POST "http://127.0.0.1:$SERVER_PORT/api/sessions" "$AUTH" "$PAYLOAD" "test" 4)
+rc=$?
+assert_eq "capture/always-503: returns failure (1) after exhausting attempts" "1" "$rc"
+assert_eq "capture/always-503: server saw exactly MAX_ATTEMPTS (3) requests" "3" "$(req_count)"
+assert_eq "capture/always-503: NO body on stdout on failure (caller sees empty → skips)" "" "$cap_body"
+# The capture helper stays SILENT on failure — the caller (session-create) logs
+# its own outcome (skip/no_rw_session). A stray 'error' entry here would
+# mis-classify that benign skip (regressed hooks.test.ts).
+assert_eq "capture/always-503: helper logs NOTHING on failure (caller owns outcome)" "0" "$(wc -l < "$LOG_FILE" | tr -d ' ')"
+stop_server
+
+# --- Test 7: _rulemetric_send_capture does NOT retry a permanent 4xx -----------
+start_server always-400
+: > "$LOG_FILE"
+_rulemetric_send_capture POST "http://127.0.0.1:$SERVER_PORT/api/sessions" "$AUTH" "$PAYLOAD" "test" 4 >/dev/null
+rc=$?
+assert_eq "capture/always-400: returns failure (1)" "1" "$rc"
+assert_eq "capture/always-400: server saw exactly 1 request (no retry on 4xx)" "1" "$(req_count)"
+stop_server
+
+# --- Test 8: "@file" payload streams a multi-MB body (reimport E2BIG fix) -----
+# session-end reimport passes "@/tmp/file" so transcripts never ride argv: a
+# single argv element bigger than the kernel per-arg limit meant curl never
+# even exec'd (E2BIG) and long sessions silently NEVER reimported. Assert a
+# 2 MB body arrives complete and byte-identical via _rulemetric_send_capture
+# (same curl invocation shape as _rulemetric_send, but echoes the response
+# so we can read back the server-computed length + sha).
+start_server echo-len
+BIG_FILE="$WORK_ROOT/big-payload.json"
+"$PYTHON" -c "import json; print(json.dumps({'content': 'x' * (2 * 1024 * 1024), 'tool': 'claude_code'}))" > "$BIG_FILE"
+expected_len=$(wc -c < "$BIG_FILE" | tr -d ' ')
+expected_sha=$("$PYTHON" -c "import hashlib,sys; print(hashlib.sha256(open(sys.argv[1],'rb').read()).hexdigest())" "$BIG_FILE")
+: > "$LOG_FILE"
+big_body=$(_rulemetric_send_capture POST "http://127.0.0.1:$SERVER_PORT/api/sessions/x/reimport" "$AUTH" "@$BIG_FILE" "test" 10)
+rc=$?
+assert_eq "atfile: returns success (0)" "0" "$rc"
+got_len=$(printf '%s' "$big_body" | "$PYTHON" -c "import json,sys; print(json.load(sys.stdin)['len'])" 2>/dev/null || echo parse-error)
+got_sha=$(printf '%s' "$big_body" | "$PYTHON" -c "import json,sys; print(json.load(sys.stdin)['sha'])" 2>/dev/null || echo parse-error)
+assert_eq "atfile: server received the full 2MB body" "$expected_len" "$got_len"
+assert_eq "atfile: body byte-identical (sha256)" "$expected_sha" "$got_sha"
+stop_server
+
 # --- Summary -----------------------------------------------------------------
 echo
 echo "Passed: $PASSES   Failed: $FAILURES"

package/scripts/session-end.sh

@@ -44,33 +44,46 @@ if ! _rulemetric_ensure_session "session-end"; then
 fi
 
 # Try to reimport with full transcript, fall back to close
+REIMPORT_FILE=""
 if [ -n "$HOOK_TRANSCRIPT_PATH" ] && [ -f "$HOOK_TRANSCRIPT_PATH" ]; then
-  CONTENT=$(cat "$HOOK_TRANSCRIPT_PATH")
-  REIMPORT_PAYLOAD="{\"content\":$(echo "$CONTENT" | jq -Rs .),\"tool\":\"$HOOK_TOOL\"}"
-  # Retry-on-503 (max-time 8 for the large transcript body); this is FOREGROUND and
-  # blocks the hook, so cap at 2 attempts (worst-case tail ~18s on a hard API hang,
-  # vs ~32s at 3) — the common fast-503 wedge still recovers in <1s. Fall back to
-  # close if it still fails after retries — a dropped reimport leaves the session EMPTY.
-  # NOTE: under headless `claude -p`, Claude Code's print-mode teardown cancels this
-  # hook ("SessionEnd hook … failed: Hook cancelled") regardless of whether this runs
-  # in the foreground or is backgrounded — verified 2026-07-05. It is a Claude Code
-  # print-mode behavior, not a capture failure (per-turn hooks still land events); do
-  # NOT try to "fix" it by detaching this call (adds no benefit, and headless is a
-  # deliberately-excluded capture vehicle).
-  _rulemetric_send POST "${RULEMETRIC_API_URL}/api/sessions/${RW_SESSION_ID}/reimport" \
-    "$AUTH_HEADER" "$REIMPORT_PAYLOAD" "session-end-reimport" 8 2 \
-    > /dev/null 2>&1 || {
-    _rulemetric_log "session-end" "fallback" "reimport_failed"
-    curl -sf --noproxy '*' --max-time 4 -X POST "${RULEMETRIC_API_URL}/api/sessions/${RW_SESSION_ID}/close" \
-      -H "$AUTH_HEADER" \
-      > /dev/null 2>&1 || \
+  # Build the payload in a TEMP FILE and stream it with curl's @file form. It
+  # must never ride argv: a long session's transcript blows the kernel per-arg
+  # exec limit (E2BIG) and curl never starts — long sessions silently NEVER
+  # reimported. jq builds {content, tool} straight from the transcript so the
+  # whole body is also never held in a shell variable.
+  REIMPORT_FILE=$(mktemp "${TMPDIR:-/tmp}/rm-reimport.XXXXXX" 2>/dev/null || true)
+  if [ -n "$REIMPORT_FILE" ] && jq -Rs --arg tool "$HOOK_TOOL" '{content: ., tool: $tool}' \
+       < "$HOOK_TRANSCRIPT_PATH" > "$REIMPORT_FILE" 2>/dev/null; then
+    # Retry-on-503; FOREGROUND, blocks the hook, so cap at 2 attempts. max-time 20
+    # gives a multi-MB body room to actually transfer on a slow uplink (worst-case
+    # hard-hang tail 20+1+20 = 41s, still under Claude Code's 60s hook timeout);
+    # the common fast-503 wedge still recovers in <1s. Fall back to close if it
+    # still fails after retries — a dropped reimport leaves the session EMPTY.
+    # NOTE: under headless `claude -p`, Claude Code's print-mode teardown cancels this
+    # hook ("SessionEnd hook … failed: Hook cancelled") regardless of whether this runs
+    # in the foreground or is backgrounded — verified 2026-07-05. It is a Claude Code
+    # print-mode behavior, not a capture failure (per-turn hooks still land events); do
+    # NOT try to "fix" it by detaching this call (adds no benefit, and headless is a
+    # deliberately-excluded capture vehicle).
+    _rulemetric_send POST "${RULEMETRIC_API_URL}/api/sessions/${RW_SESSION_ID}/reimport" \
+      "$AUTH_HEADER" "@$REIMPORT_FILE" "session-end-reimport" 20 2 \
+      > /dev/null 2>&1 || {
+      _rulemetric_log "session-end" "fallback" "reimport_failed"
+      _rulemetric_send POST "${RULEMETRIC_API_URL}/api/sessions/${RW_SESSION_ID}/close" \
+        "$AUTH_HEADER" '{}' "session-end-close" 4 2 > /dev/null 2>&1 || \
+        _rulemetric_log "session-end" "error" "close_failed"
+    }
+  else
+    _rulemetric_log "session-end" "fallback" "reimport_payload_build_failed"
+    _rulemetric_send POST "${RULEMETRIC_API_URL}/api/sessions/${RW_SESSION_ID}/close" \
+      "$AUTH_HEADER" '{}' "session-end-close" 4 2 > /dev/null 2>&1 || \
       _rulemetric_log "session-end" "error" "close_failed"
-  }
+  fi
+  [ -n "$REIMPORT_FILE" ] && rm -f "$REIMPORT_FILE" 2>/dev/null || true
 else
   # No transcript available — just close the session
-  curl -sf --noproxy '*' --max-time 4 -X POST "${RULEMETRIC_API_URL}/api/sessions/${RW_SESSION_ID}/close" \
-    -H "$AUTH_HEADER" \
-    > /dev/null 2>&1 || \
+  _rulemetric_send POST "${RULEMETRIC_API_URL}/api/sessions/${RW_SESSION_ID}/close" \
+    "$AUTH_HEADER" '{}' "session-end-close" 4 2 > /dev/null 2>&1 || \
     _rulemetric_log "session-end" "error" "close_failed"
 fi
 
@@ -86,19 +99,23 @@ _rulemetric_log "session-end" "success"
 if [ "$HOOK_TOOL" = "claude_code" ]; then
   INSTR_SNAPSHOT=$(rulemetric hooks emit-instructions --project-dir "${HOOK_CWD:-$(pwd)}" 2>/dev/null || true)
   if [ -n "$INSTR_SNAPSHOT" ]; then
-    curl -sf --noproxy '*' --max-time 5 -X POST "${RULEMETRIC_API_URL}/api/sessions/${RW_SESSION_ID}/context-snapshots" \
-      -H "$AUTH_HEADER" \
-      -H "Content-Type: application/json" \
-      -d "$INSTR_SNAPSHOT" > /dev/null 2>&1 || _rulemetric_log "session-end" "warn" "instruction_snapshot_failed"
+    # Bounded 503/429 retry — this snapshot is the ONLY instruction-linking
+    # signal a hooks-only (no-proxy) session ever emits; a one-shot curl made
+    # one transient shed permanently unlink the session's instructions.
+    _rulemetric_send POST "${RULEMETRIC_API_URL}/api/sessions/${RW_SESSION_ID}/context-snapshots" \
+      "$AUTH_HEADER" "$INSTR_SNAPSHOT" "session-end-instr-snapshot" 5 2 \
+      > /dev/null 2>&1 || _rulemetric_log "session-end" "warn" "instruction_snapshot_failed"
   fi
 fi
 
 # ── Auto-link instructions from context snapshots ──
-# Fire-and-forget: link any captured context to instruction records
-(curl -sf --noproxy '*' --max-time 8 -X POST "${RULEMETRIC_API_URL}/api/sessions/link-instructions" \
-  -H "$AUTH_HEADER" \
-  -H "Content-Type: application/json" \
-  -d '{}' > /dev/null 2>&1) &
+# Fire-and-forget (backgrounded), but with the same bounded 503/429 retry as
+# the other session-end writes — one transient shed used to drop it silently.
+# Scoped to THIS session: the API treats an unscoped body as a no-op (the
+# account-wide scan is explicit-backfill only). RW_SESSION_ID is
+# UUID-validated by _ensure-session, so it is safe to interpolate into JSON.
+(_rulemetric_send POST "${RULEMETRIC_API_URL}/api/sessions/link-instructions" \
+  "$AUTH_HEADER" "{\"sessionId\":\"$RW_SESSION_ID\"}" "session-end-link" 8 > /dev/null 2>&1) &
 
 # ── Auto-enrich from local session-meta ──
 # For Claude Code: read local session-meta file

package/scripts/session-start.sh

@@ -59,21 +59,15 @@ _rulemetric_check_auth() {
 
 _rulemetric_check_auth
 
-# ── Gateway auto-recovery ──
+# ── Gateway auto-recovery + stale-addon convergence ──
 # Ensure the gateway proxy is running so Claude Code can always connect.
 # The gateway routes direct when mitmproxy is off, so this is non-breaking.
-GATEWAY_PID_FILE="$HOME/.config/rulemetric/gateway.pid"
-
-if [ -f "$GATEWAY_PID_FILE" ]; then
-  GATEWAY_PID=$(cat "$GATEWAY_PID_FILE" 2>/dev/null)
-  if ! kill -0 "$GATEWAY_PID" 2>/dev/null; then
-    # Gateway crashed — respawn it
-    rulemetric gateway ensure 2>/dev/null || true
-  fi
-else
-  # No PID file — try to start gateway
-  rulemetric gateway ensure 2>/dev/null || true
-fi
+# UNCONDITIONAL (not gated on the PID quick-check): `gateway ensure` is also
+# the component that detects a HEALTHY proxy running a stale addon after an
+# `npm i -g` upgrade (the gateway↔addon drift restart is circular — both
+# compare versions frozen at their own spawn) and restarts it. Backgrounded so
+# the node boot never delays the hook.
+(rulemetric gateway ensure > /dev/null 2>&1 || true) &
 
 # ── Proxy auto-recovery ──
 # Ensure the capture proxy is running so events + context are captured.