@quantiya/codevibe-claude-plugin 2.0.5 → 2.0.7

package/hooks/common.sh

@@ -81,6 +81,624 @@ read_json_input() {
   cat
 }
 
+# A Claude Companion daemon belongs to one root CLI inside a tmux instance, not
+# to whichever descendant hook happens to notice that the daemon died. Keep the
+# root native session owner outside the daemon so a nested `claude` startup
+# cannot become owner merely by winning the recovery race.
+_claude_root_owner_file() {
+  local tmux_session="${CODEVIBE_TMUX_SESSION:-}"
+  [ -n "$tmux_session" ] || return 1
+  echo "${CODEVIBE_TMPDIR}/codevibe-claude-root-${tmux_session}.id"
+}
+
+_read_claude_root_session() {
+  local owner_file owner
+  owner_file=$(_claude_root_owner_file) || return 1
+  [ -f "$owner_file" ] || return 1
+  owner=$(head -n 1 "$owner_file" 2>/dev/null | tr -d '\r\n')
+  [ -n "$owner" ] || return 1
+  echo "$owner"
+}
+
+# SessionStart is the only hook allowed to initialize the tmux-scoped root
+# record. A foreign `source=startup` never replaces it. Claude's supported
+# in-process lifecycle transitions (/resume, /clear, compaction) deliberately
+# advance the stored native session so a later daemon crash can self-heal the
+# current root conversation rather than an older one.
+record_claude_root_session() {
+  local session_id="$1" source="${2:-}"
+  [ -n "$session_id" ] || return 1
+  local owner_file current tmp
+  owner_file=$(_claude_root_owner_file) || {
+    echo "$session_id"
+    return 0
+  }
+
+  if [ ! -f "$owner_file" ]; then
+    (
+      umask 077
+      set -C
+      printf '%s\n' "$session_id" > "$owner_file"
+    ) 2>/dev/null || true
+  else
+    case "$source" in
+      resume|clear|compact)
+        current=$(_read_claude_root_session 2>/dev/null || true)
+        if [ "$current" != "$session_id" ]; then
+          tmp="${owner_file}.tmp.$$"
+          (umask 077; printf '%s\n' "$session_id" > "$tmp") \
+            && mv -f "$tmp" "$owner_file"
+          rm -f "$tmp"
+        fi
+        ;;
+    esac
+  fi
+
+  _read_claude_root_session 2>/dev/null || echo "$session_id"
+}
+
+# (#638) Ensure an MCP daemon is running for the given session; echo its port
+# on stdout. Idempotent reuse-or-launch:
+#   - Reuse: if the instance mapping's PID is alive AND has a port, echo it
+#     (rewriting the mapping to the current session id, matching the legacy
+#     session-start reuse path).
+#   - Launch: otherwise, delete any STALE port file (a leftover from a prior
+#     dead daemon — the readiness wait keys off port-file existence, so a stale
+#     file makes the wait read the OLD dead port), spawn a fresh daemon with the
+#     SAME args/env session-start.sh used, wait for it to publish its port,
+#     write the mapping, and echo the port.
+# Returns 0 with the port on stdout on success, non-zero on failure. This is
+# factored out of session-start.sh so send_to_mcp's transport-failure retry can
+# relaunch a dead daemon and re-deliver a lost hook event.
+# Usage: ensure_mcp_daemon <session_id> [exclude_port] [exclude_pid]   ->  echoes port
+# (#638 F7) True (0) iff PID is still a codevibe-claude daemon process. Guards the
+# daemon-reuse path against macOS PID reuse (~32K PIDs wrap around, so a stale
+# mapping's PID could belong to a completely unrelated user process). Moved here from
+# session-start.sh so BOTH the hook reuse path AND the session-start sweep/dedup/reuse
+# share ONE definition. Matches the cache path (.../codevibe-claude/X.Y.Z/dist/server.js)
+# and the dev path (.../codevibe-claude-plugin/dist/server.js).
+is_codevibe_daemon() {
+  local pid="$1"
+  local cmd
+  cmd=$(ps -o command= -p "$pid" 2>/dev/null)
+  case "$cmd" in
+    *node*codevibe-claude*server.js*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+# (#638 F7/F8) Probe a port's /health and confirm it is OUR daemon: HTTP 200 AND a
+# top-level `.service == "codevibe-claude"` marker parsed with jq (NOT a substring
+# match — a foreign body merely CONTAINING or nesting the marker text must NOT pass).
+# Catches a live-but-wedged / wrong-port / foreign-server-on-a-recycled-port daemon
+# that the PID-identity check alone would trust. Bounded via --max-time so a wedged
+# socket can't hang the hook.
+_probe_claude_health() {
+  local port="$1" resp code body
+  [ -n "$port" ] || return 1
+  resp=$(curl -s --max-time 2 -w "\n%{http_code}" "http://localhost:${port}/health" 2>/dev/null)
+  code=$(echo "$resp" | tail -n 1)
+  body=$(echo "$resp" | sed '$d')
+  [ "$code" = "200" ] || return 1
+  echo "$body" | jq -e '.service == "codevibe-claude"' > /dev/null 2>&1
+}
+
+# Helper: if a live daemon already serves this Claude Code instance (per the tmux
+# instance mapping), echo its port (rewriting the mapping to the daemon's durable
+# root owner) and return 0; else return 1. The hook that triggered reuse can be a
+# nested Claude process, so callers must pass the root identity used for daemon
+# ownership, not the trigger identity used only for event delivery. Kept separate
+# so both the fast-path reuse AND the under-lock double-check use the same logic.
+_reuse_live_mcp_daemon() {
+  local daemon_session_id="$1" mapping_file="$2"
+  [ -n "$mapping_file" ] && [ -f "$mapping_file" ] || return 1
+  local ep pp
+  ep=$(jq -r '.port // empty' "$mapping_file" 2>/dev/null)
+  pp=$(jq -r '.pid // empty' "$mapping_file" 2>/dev/null)
+  [ -n "$pp" ] && [ -n "$ep" ] || return 1
+  # (#638 F7) PID-alive is NOT sufficient. Require, in order:
+  #  1. ps -p       — the PID exists
+  #  2. is_codevibe_daemon — the PID's command is still OUR daemon (cheap, no
+  #     network; catches a recycled PID handed to a foreign process on wake-from-sleep)
+  #  3. /health marker — the port answers as codevibe-claude (catches a live-but-wedged
+  #     or wrong-port daemon the PID-identity check alone would trust)
+  # Only when ALL pass do we rewrite the mapping to the current session and reuse it.
+  ps -p "$pp" > /dev/null 2>&1 || return 1
+  is_codevibe_daemon "$pp" || return 1
+  _probe_claude_health "$ep" || return 1
+  echo "{\"session\":\"$daemon_session_id\",\"port\":$ep,\"pid\":$pp}" > "$mapping_file"
+  echo "$ep"
+  return 0
+}
+
+# (#638 J1) Resolve the pid our records associate with <port> for <session_id>:
+# the tmux instance mapping's pid when the mapping names that port, else the
+# session pidfile when the session port file names that port (the no-tmux
+# fallback) — the SAME resolution order the H2 wedged-daemon reap uses. Echoes
+# the pid (return 0), or nothing (return 1) when no record names the port.
+# Callers use this to SNAPSHOT a transport-failed daemon's identity AT EXCLUSION
+# TIME — right when the POST failed, BEFORE calling ensure_mcp_daemon (which may
+# wait on the instance lock while a concurrent hook reaps + relaunches).
+_resolve_mcp_daemon_pid_for_port() {
+  local session_id="$1" port="$2"
+  [ -n "$port" ] || return 1
+  local pid=""
+  local tmux_session="${CODEVIBE_TMUX_SESSION:-}"
+  if [ -n "$tmux_session" ]; then
+    local mapping_file="${CODEVIBE_TMPDIR}/codevibe-claude-instance-${tmux_session}.json"
+    if [ -f "$mapping_file" ] \
+       && [ "$(jq -r '.port // empty' "$mapping_file" 2>/dev/null)" = "$port" ]; then
+      pid=$(jq -r '.pid // empty' "$mapping_file" 2>/dev/null)
+    fi
+  fi
+  if [ -z "$pid" ] && [ -n "$session_id" ]; then
+    local pid_file="${CODEVIBE_TMPDIR}/codevibe-claude-${session_id}.pid"
+    local port_file="${CODEVIBE_TMPDIR}/codevibe-claude-${session_id}.port"
+    if [ -f "$pid_file" ] && [ -f "$port_file" ] \
+       && [ "$(cat "$port_file" 2>/dev/null)" = "$port" ]; then
+      pid=$(cat "$pid_file" 2>/dev/null)
+    fi
+  fi
+  [ -n "$pid" ] || return 1
+  echo "$pid"
+}
+
+# (#638 J1) True (0) iff the reuse candidate that just passed _reuse_live_mcp_daemon
+# IS the excluded (wedged) daemon. exclude_port alone is NOT identity: ephemeral
+# ports get recycled, so a concurrent hook's fresh winner can legitimately come up
+# on the SAME port the wedged daemon held — skipping reuse (and then reaping) on a
+# port match alone would kill that healthy winner (it passes is_codevibe_daemon
+# because it IS a codevibe daemon — just a different lifecycle) and break
+# exactly-once launch. So whenever the caller could snapshot the wedged daemon's
+# pid at exclusion time, require the candidate's CURRENT pid (the mapping's pid,
+# just rewritten by _reuse_live_mcp_daemon from the verified daemon) to match too.
+# With no exclude_pid (no mapping/pidfile named the port at snapshot time) fall
+# back to port-only — no identity is available; the eventual reap is still
+# is_codevibe-guarded, which bounds the damage to our own daemon class.
+# (#638 K1) The candidate's (port, pid) MUST come from ONE atomic mapping parse.
+# Reading .pid in a SEPARATE jq call from the reuse read opened a TOCTOU: a
+# concurrent DIFFERENT-port winner can rewrite the mapping between the reuse
+# result and this check, pairing the stale failed port with the NEW winner's pid
+# → pid mismatch vs exclude_pid → the wedged port was accepted for reuse and the
+# retry POST hit the dead port (bounded drop, but exactly what J1 exists to
+# prevent). So parse [.port, .pid] in a single jq read; if the mapping's port no
+# longer equals the candidate port, the mapping has MOVED ON → the candidate is
+# STALE → treat it as excluded (never reuse the old port; ensure falls through
+# to the launch/reap path, which re-checks under the lock). Same-port+same-pid →
+# excluded and same-port+different-pid → legitimate-winner semantics unchanged.
+# (The codex sibling _codex_candidate_is_excluded has no such window: its
+# candidate pid comes from a /health probe against the candidate port itself, so
+# port and pid are inherently consistent.)
+# Usage: _mcp_candidate_is_excluded <cand_port> <mapping_file> <exclude_port> <exclude_pid>
+_mcp_candidate_is_excluded() {
+  local cand_port="$1" mapping_file="$2" exclude_port="$3" exclude_pid="$4"
+  [ -n "$exclude_port" ] || return 1
+  [ "$cand_port" = "$exclude_port" ] || return 1
+  [ -n "$exclude_pid" ] || return 0          # port-only fallback (no snapshot identity)
+  local map_port="" map_pid=""
+  if [ -n "$mapping_file" ] && [ -f "$mapping_file" ]; then
+    # (#638 K1) ONE read, ONE parse — port and pid from the SAME mapping state.
+    # (#638 L1) Trust the tuple ONLY when jq itself SUCCEEDED and emitted exactly
+    # one TSV record: a valid JSON document followed by malformed trailing input
+    # makes jq print the record and THEN exit nonzero — without the exit-status
+    # check that partial output would be trusted, bypassing the conservative
+    # port-only fallback. Multi-line output (>1 record) is equally untrusted.
+    local map_pair
+    if map_pair=$(jq -r '[(.port // "" | tostring), (.pid // "" | tostring)] | @tsv' "$mapping_file" 2>/dev/null) \
+        && [ "$(printf '%s' "$map_pair" | wc -l | tr -d ' ')" = "0" ]; then
+      map_port="${map_pair%%$'\t'*}"
+      map_pid="${map_pair#*$'\t'}"
+      [ "$map_port" = "$map_pair" ] && { map_port=""; map_pid=""; }   # no tab: empty/garbled record
+    fi   # jq nonzero or multi-record → map_port/map_pid stay empty → port-only fallback
+  fi
+  if [ -n "$map_port" ] && [ "$map_port" != "$cand_port" ]; then
+    # (#638 K1) Mapping moved on to a different port since the reuse read — the
+    # candidate is stale. Excluded: do NOT hand back the old port.
+    return 0
+  fi
+  [ -n "$map_pid" ] || return 0              # candidate pid unknowable → conservative port-only
+  [ "$map_pid" = "$exclude_pid" ]
+}
+
+# (#638 G5/H2/H3) THE identity-guarded reap: TERM → bounded wait → identity
+# re-check → KILL → settle. Identity (is_codevibe_daemon) is re-verified
+# immediately before EVERY signal — the PID can die after the SIGTERM and be
+# recycled to an unrelated process during the settle poll, so signaling blind
+# could kill a foreign process. Works for BOTH our own background child (`wait`
+# collects its status instantly, closing the PID-reuse window) and a non-child
+# daemon from a prior hook (`wait` is a silent no-op there; the bounded ps-poll
+# provides the settle). Returns 0 when the daemon is provably gone, 1 when the
+# PID was not (or stopped being) our daemon and was left alone.
+_reap_codevibe_daemon_pid() {
+  local pid="$1" why="$2"
+  [ -n "$pid" ] || return 1
+  if ! is_codevibe_daemon "$pid"; then
+    log "WARN" "reap($why): pid $pid is not our daemon (recycled/replaced) — not signaling"
+    return 1
+  fi
+  kill "$pid" 2>/dev/null            # SIGTERM: let it run its graceful shutdown
+  local reap=0
+  while [ $reap -lt 10 ] && ps -p "$pid" > /dev/null 2>&1; do
+    sleep 0.2
+    reap=$((reap + 1))
+  done
+  if ps -p "$pid" > /dev/null 2>&1; then
+    # (#638 G5) Re-verify identity IMMEDIATELY before the KILL escalation.
+    if is_codevibe_daemon "$pid"; then
+      log "WARN" "reap($why): pid $pid ignored SIGTERM, sending SIGKILL"
+      kill -9 "$pid" 2>/dev/null
+      # SIGKILL is un-ignorable: collect our own background child promptly (no-op
+      # for a non-child), then bound the non-child settle with a short ps-poll.
+      wait "$pid" 2>/dev/null
+      local settle=0
+      while [ $settle -lt 5 ] && ps -p "$pid" > /dev/null 2>&1; do
+        sleep 0.1
+        settle=$((settle + 1))
+      done
+    else
+      log "WARN" "reap($why): pid $pid is no longer our daemon (recycled/replaced) — NOT sending SIGKILL"
+      return 1
+    fi
+  else
+    # (#638 G5) Already exited from SIGTERM — `wait` on our own background child
+    # returns its saved status instantly (no blocking) and closes the reuse window.
+    wait "$pid" 2>/dev/null
+  fi
+  return 0
+}
+
+# (#638 G3) Owner-crash cleanup for the relaunch lock. Installed as an EXIT trap for
+# the lock-HELD region of ensure_mcp_daemon only. ensure_mcp_daemon always runs in a
+# command-substitution subshell at its call sites (session-start.sh `$(...)`,
+# send_to_mcp's retry `$(...)`), so the trap scope is that subshell — it never leaks
+# into the sourcing hook script. If the lock owner is interrupted mid-cold-start
+# (TERM/INT/HUP or any abnormal exit), this:
+#  (a) (#638 H3) FIRST re-checks whether the child already PUBLISHED its port file
+#      in the window between the port-file write and the publish-clear of
+#      CODEVIBE_ENSURE_CHILD_PID. A published child is a HEALTHY daemon — do NOT
+#      signal it; instead FINALIZE the publication (write the instance mapping if
+#      missing so hooks can route to it) and just release the lock. Pre-H3 the trap
+#      TERMed the just-published daemon (and rmdir'd while its shutdown was still
+#      async), killing a healthy daemon the next hook then had to relaunch.
+#      Safe keying: the launch path `rm -f "$port_file"`s BEFORE spawning, so while
+#      CODEVIBE_ENSURE_CHILD_PID is set, an existing port file was written by the child.
+#  (b) reaps a genuinely-UNPUBLISHED child via the bounded identity-rechecked
+#      TERM→wait→KILL helper (pre-H3 it sent a single bare TERM and released the
+#      lock immediately, leaving the child's async shutdown racing the next owner);
+#  (c) releases the lock immediately instead of stranding it for the +2min mtime
+#      reaper (which stays as the backstop for the untrappable SIGKILL case).
+CODEVIBE_ENSURE_LOCK_DIR=""
+CODEVIBE_ENSURE_CHILD_PID=""
+CODEVIBE_ENSURE_PORT_FILE=""
+CODEVIBE_ENSURE_MAPPING_FILE=""
+CODEVIBE_ENSURE_SESSION_ID=""
+_codevibe_ensure_lock_cleanup() {
+  if [ -n "$CODEVIBE_ENSURE_CHILD_PID" ]; then
+    if [ -n "$CODEVIBE_ENSURE_PORT_FILE" ] && [ -f "$CODEVIBE_ENSURE_PORT_FILE" ]; then
+      # (#638 H3) PUBLISHED between port-file write and publish-clear → finalize.
+      local pub_port
+      pub_port=$(cat "$CODEVIBE_ENSURE_PORT_FILE" 2>/dev/null)
+      if [ -n "$pub_port" ] && [ -n "$CODEVIBE_ENSURE_MAPPING_FILE" ] && [ ! -f "$CODEVIBE_ENSURE_MAPPING_FILE" ]; then
+        echo "{\"session\":\"$CODEVIBE_ENSURE_SESSION_ID\",\"port\":$pub_port,\"pid\":$CODEVIBE_ENSURE_CHILD_PID}" > "$CODEVIBE_ENSURE_MAPPING_FILE"
+      fi
+      log "WARN" "ensure_mcp_daemon: interrupted AFTER child published (pid $CODEVIBE_ENSURE_CHILD_PID, port ${pub_port:-unknown}) — finalized publication, NOT signaling (#638 H3)"
+    else
+      log "WARN" "ensure_mcp_daemon: interrupted while holding relaunch lock — reaping unpublished child pid $CODEVIBE_ENSURE_CHILD_PID (#638 H3 bounded reap)"
+      _reap_codevibe_daemon_pid "$CODEVIBE_ENSURE_CHILD_PID" "owner-trap unpublished child"
+    fi
+  fi
+  if [ -n "$CODEVIBE_ENSURE_LOCK_DIR" ]; then
+    rmdir "$CODEVIBE_ENSURE_LOCK_DIR" 2>/dev/null
+  fi
+  CODEVIBE_ENSURE_LOCK_DIR=""
+  CODEVIBE_ENSURE_CHILD_PID=""
+  CODEVIBE_ENSURE_PORT_FILE=""
+  CODEVIBE_ENSURE_MAPPING_FILE=""
+  CODEVIBE_ENSURE_SESSION_ID=""
+}
+
+ensure_mcp_daemon() {
+  local session_id="$1"
+  # (#638 H2) Optional: a port KNOWN-BAD for /event delivery (send_to_mcp's POST
+  # timed out / transport-failed against it). The reuse fast paths verify /health
+  # only — a daemon can answer /health 200 while its /event pipeline is WEDGED, so
+  # without the exclusion the transport-failure retry reused the SAME wedged port
+  # and the promised relaunch never happened (recovery dead until the daemon
+  # un-wedged). When the reuse candidate's port equals exclude_port we SKIP reuse,
+  # take the instance lock, identity-reap that daemon, and launch exactly once.
+  # Only send_to_mcp's transport-failure retry passes this; all other callers keep
+  # the exclusion-free fast path unchanged.
+  local exclude_port="$2"
+  # (#638 J1) Optional: the pid the caller's records associated with exclude_port
+  # AT EXCLUSION TIME (snapshotted via _resolve_mcp_daemon_pid_for_port right when
+  # the POST transport-failed). Port alone is NOT identity — a concurrent hook's
+  # fresh winner can come up on the SAME recycled ephemeral port — so skip-reuse
+  # and the wedged reap fire ONLY when the candidate matches BOTH port AND pid; a
+  # same-port/different-pid candidate is a legitimate winner and is REUSED. Empty
+  # when no record named the port at snapshot time → port-only fallback (pre-J1
+  # behavior; the reap stays is_codevibe-guarded).
+  local exclude_pid="$3"
+  if [ -z "$session_id" ]; then
+    log "ERROR" "ensure_mcp_daemon: no session_id"
+    return 1
+  fi
+
+  # Plugin root = parent of the hooks dir that DEFINES this function (common.sh),
+  # regardless of which hook script sourced it. BASH_SOURCE[0] is common.sh.
+  local hooks_dir plugin_root
+  hooks_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  plugin_root="$(cd "$hooks_dir/.." && pwd)"
+
+  local tmux_session="${CODEVIBE_TMUX_SESSION:-}"
+  # The routing hook's session_id may belong to a nested Claude process. The
+  # daemon bootstrap identity must come from the durable root record created by
+  # the root SessionStart hook, falling back only for non-tmux/legacy launches.
+  local daemon_session_id="$session_id"
+  if [ -n "$tmux_session" ]; then
+    local recorded_root
+    recorded_root=$(_read_claude_root_session 2>/dev/null || true)
+    [ -n "$recorded_root" ] && daemon_session_id="$recorded_root"
+  fi
+  local mapping_file=""
+  if [ -n "$tmux_session" ]; then
+    mapping_file="${CODEVIBE_TMPDIR}/codevibe-claude-instance-${tmux_session}.json"
+  fi
+  local pid_file="${CODEVIBE_TMPDIR}/codevibe-claude-${daemon_session_id}.pid"
+  local port_file="${CODEVIBE_TMPDIR}/codevibe-claude-${daemon_session_id}.port"
+  # (#638 G3) Key the relaunch lock to the tmux INSTANCE, not the session id. The
+  # daemon being launched is the per-tmux-instance daemon (mapping
+  # codevibe-claude-instance-<tmux>.json), but the old session-scoped
+  # ${port_file}.lock let two hooks with DIFFERENT session ids in the SAME tmux
+  # (e.g. /resume old + new session racing) take DIFFERENT locks, both pass the
+  # under-lock double-check (mapping not yet written), and launch TWO daemons.
+  # Lock scope must match daemon/mapping scope. Fallback: when no tmux var is set
+  # there is no instance mapping (mapping_file empty) — daemon scope degrades to
+  # session scope, so the session-scoped lock matches it, same as before.
+  local lock_dir
+  if [ -n "$tmux_session" ]; then
+    lock_dir="${CODEVIBE_TMPDIR}/codevibe-claude-instance-${tmux_session}.lock"
+  else
+    lock_dir="${port_file}.lock"
+  fi
+
+  # ── Fast path: reuse a live daemon (no lock needed) ──
+  local reuse
+  if reuse=$(_reuse_live_mcp_daemon "$daemon_session_id" "$mapping_file"); then
+    if _mcp_candidate_is_excluded "$reuse" "$mapping_file" "$exclude_port" "$exclude_pid"; then
+      # (#638 H2) Health-passing but /event-wedged daemon — do NOT reuse; fall
+      # through to the lock so it gets reaped + relaunched. Keep the mapping for
+      # now: it carries the wedged daemon's PID for the identity-guarded reap.
+      # (#638 J1) Only when the candidate matches port AND (when snapshotted) pid
+      # — a same-port/different-pid candidate is a fresh winner and reuses above.
+      log "WARN" "ensure_mcp_daemon: reuse candidate port $reuse is the excluded (wedged) daemon — skipping reuse, will reap + relaunch (#638 H2/J1)"
+    else
+      log "INFO" "ensure_mcp_daemon: reusing live daemon (port $reuse)"
+      echo "$reuse"
+      return 0
+    fi
+  elif [ -n "$mapping_file" ] && [ -f "$mapping_file" ]; then
+    log "INFO" "ensure_mcp_daemon: mapping daemon not alive, removing stale mapping"
+    rm -f "$mapping_file"
+  fi
+
+  # ── Serialize the LAUNCH (double-checked locking) ──
+  # Two near-simultaneous hooks that both hit a dead port would otherwise BOTH
+  # relaunch → two daemons per tmux session (duplicate mobile events + double
+  # heartbeat). A mkdir-lock (atomic acquire) elects ONE launcher; the loser(s)
+  # wait briefly and RE-READ the mapping to reuse the winner's daemon.
+  # Reap a clearly-abandoned lock first (holder crashed mid-launch). The lock is
+  # now held for the FULL cold start (up to ~60s — see the readiness wait below),
+  # so the reaper threshold MUST stay strictly above that max hold (>2min ⇒
+  # abandoned) or it could reap a live, slow-starting holder.
+  if [ -d "$lock_dir" ] && [ -n "$(find "$lock_dir" -maxdepth 0 -mmin +2 2>/dev/null)" ]; then
+    log "WARN" "ensure_mcp_daemon: removing stale relaunch lock $lock_dir"
+    rmdir "$lock_dir" 2>/dev/null
+  fi
+
+  # Cold-start readiness cap (0.5s units). The elected launcher HOLDS the lock for
+  # the whole cold start, up to this cap (see the readiness wait below). Overridable
+  # for tests; production default = 120 × 0.5s = 60s.
+  local max_wait="${CODEVIBE_DAEMON_MAX_WAIT_UNITS:-120}"
+  # (#638 F2) The contender's acquire/reuse-poll bound MUST be ≥ the launcher's max
+  # hold, or a slow launch (the incident: woken Mac + returning network → a 60s cold
+  # start) makes the contender abandon at ~12s BEFORE the winner has published its
+  # mapping — the contender's last-chance reuse then fails and the hook's event is
+  # silently DROPPED. Derive it from the cap (+5s margin) so it always outlasts the
+  # launcher and reuses the winner's daemon instead of dropping.
+  local contender_wait=$((max_wait + 10))
+
+  local acquired=0 waited=0
+  while [ $waited -lt $contender_wait ]; do   # ≥ cold-start cap + margin; no spin
+    if mkdir "$lock_dir" 2>/dev/null; then acquired=1; break; fi
+    sleep 0.5
+    waited=$((waited + 1))
+    # While the winner launches, try to reuse its daemon as soon as it's up.
+    # (#638 H2) Never hand back the excluded (wedged) daemon from here either.
+    # (#638 J1) port+pid match — a same-port fresh winner is reused, not skipped.
+    if reuse=$(_reuse_live_mcp_daemon "$daemon_session_id" "$mapping_file"); then
+      if _mcp_candidate_is_excluded "$reuse" "$mapping_file" "$exclude_port" "$exclude_pid"; then
+        continue   # wedged candidate — keep waiting for the lock to reap+relaunch
+      fi
+      log "INFO" "ensure_mcp_daemon: reusing daemon launched concurrently (port $reuse)"
+      echo "$reuse"
+      return 0
+    fi
+  done
+  if [ $acquired -ne 1 ]; then
+    # Couldn't acquire within the bound — last-chance reuse, else give up.
+    # (#638 H2) The excluded (wedged) daemon is never an acceptable last-chance
+    # answer. (#638 J1) port+pid match — a same-port fresh winner IS acceptable.
+    if reuse=$(_reuse_live_mcp_daemon "$daemon_session_id" "$mapping_file") \
+       && ! _mcp_candidate_is_excluded "$reuse" "$mapping_file" "$exclude_port" "$exclude_pid"; then
+      echo "$reuse"; return 0
+    fi
+    log "WARN" "ensure_mcp_daemon: could not acquire relaunch lock $lock_dir within timeout"
+    return 1
+  fi
+
+  # (#638 G3) LOCK IS HELD from here to the release rmdir. Install the owner-crash
+  # cleanup so an interrupted owner releases the lock + reaps its unpublished child.
+  # Catchable signals route through `exit` (conventional 128+signum codes) so the
+  # EXIT trap runs; SIGKILL is untrappable — the +2min mtime reaper is that backstop.
+  CODEVIBE_ENSURE_LOCK_DIR="$lock_dir"
+  CODEVIBE_ENSURE_CHILD_PID=""
+  # (#638 H3) Publication context for the owner-crash trap: while CHILD_PID is
+  # set, an EXISTING port file was provably written by the child (the launch path
+  # rm -f's it first), so the trap can distinguish published from unpublished and
+  # finalize (mapping write) instead of reaping a healthy daemon.
+  CODEVIBE_ENSURE_PORT_FILE="$port_file"
+  CODEVIBE_ENSURE_MAPPING_FILE="$mapping_file"
+  CODEVIBE_ENSURE_SESSION_ID="$daemon_session_id"
+  trap '_codevibe_ensure_lock_cleanup' EXIT
+  trap 'exit 129' HUP
+  trap 'exit 130' INT
+  trap 'exit 143' TERM
+
+  # ── Double-check UNDER the lock: did a concurrent hook already bring one up? ──
+  # (#638 H2) The excluded (wedged) daemon is not "already live" — fall through.
+  # (#638 J1) port+pid match — a same-port fresh winner IS "already live": reuse.
+  if reuse=$(_reuse_live_mcp_daemon "$daemon_session_id" "$mapping_file") \
+     && ! _mcp_candidate_is_excluded "$reuse" "$mapping_file" "$exclude_port" "$exclude_pid"; then
+    rmdir "$lock_dir" 2>/dev/null
+    trap - EXIT HUP INT TERM   # (#638 G3) lock released — clear the crash-cleanup trap
+    CODEVIBE_ENSURE_LOCK_DIR=""
+    CODEVIBE_ENSURE_PORT_FILE=""
+    CODEVIBE_ENSURE_MAPPING_FILE=""
+    CODEVIBE_ENSURE_SESSION_ID=""
+    log "INFO" "ensure_mcp_daemon: daemon already live under lock (port $reuse)"
+    echo "$reuse"
+    return 0
+  fi
+
+  # ── (#638 H2) Reap the WEDGED daemon before relaunching ──
+  # We hold the instance lock and the reuse candidate (if any) was the excluded
+  # port: a daemon that answers /health but whose /event pipeline is wedged.
+  # Leaving it alive would leak an orphan that keeps winning /health-based reuse.
+  # Resolve its PID (instance mapping first; session pid/port file pair as the
+  # no-tmux fallback) and identity-reap it (TERM→wait→KILL, G5 discipline).
+  if [ -n "$exclude_port" ]; then
+    local wedged_pid="" wedged_src=""
+    if [ -n "$exclude_pid" ]; then
+      # (#638 J1) The caller SNAPSHOTTED the wedged daemon's identity (port, pid)
+      # at exclusion time — right when the POST transport-failed. Target THAT pid:
+      # the records may since have been rewritten by a concurrent hook's fresh
+      # winner (possibly on the SAME recycled port), and re-resolving from them
+      # here could reap the healthy winner. The identity-guarded reap still
+      # refuses a dead or foreign (recycled) pid.
+      wedged_pid="$exclude_pid"
+      wedged_src="snapshot"
+    elif [ -n "$mapping_file" ] && [ -f "$mapping_file" ] \
+       && [ "$(jq -r '.port // empty' "$mapping_file" 2>/dev/null)" = "$exclude_port" ]; then
+      # (#638 J1) No snapshot pid (no record named the port at exclusion time):
+      # port-only fallback — resolve from the current records, pre-J1 behavior.
+      # No identity is available; the reap below is still is_codevibe-guarded.
+      wedged_pid=$(jq -r '.pid // empty' "$mapping_file" 2>/dev/null)
+      wedged_src="mapping"
+    elif [ -f "$pid_file" ] && [ -f "$port_file" ] \
+         && [ "$(cat "$port_file" 2>/dev/null)" = "$exclude_port" ]; then
+      wedged_pid=$(cat "$pid_file" 2>/dev/null)
+      wedged_src="pidfile"
+    fi
+    if [ -n "$wedged_pid" ]; then
+      log "WARN" "ensure_mcp_daemon: reaping wedged daemon pid $wedged_pid on excluded port $exclude_port (via $wedged_src) before relaunch (#638 H2)"
+      _reap_codevibe_daemon_pid "$wedged_pid" "wedged /event on port $exclude_port"
+      # Whether reaped or identity-mismatched (foreign PID), the records naming
+      # this pid are provably stale — remove them so nothing routes there.
+      # (#638 J1) Remove ONLY records that name the WEDGED pid — a concurrent
+      # winner's fresh mapping/pidfile (same port, different pid) must survive.
+      if [ -n "$mapping_file" ] && [ -f "$mapping_file" ] \
+         && [ "$(jq -r '.pid // empty' "$mapping_file" 2>/dev/null)" = "$wedged_pid" ]; then
+        rm -f "$mapping_file"
+      fi
+      if [ -f "$pid_file" ] && [ "$(cat "$pid_file" 2>/dev/null)" = "$wedged_pid" ]; then
+        rm -f "$pid_file"
+      fi
+    else
+      log "WARN" "ensure_mcp_daemon: excluded port $exclude_port has no discoverable daemon pid (mapping/pidfile absent or mismatched) — relaunching without reap (#638 H2)"
+    fi
+  fi
+
+  # ── Launch a fresh daemon (single cleanup point: rmdir at the end) ──
+  # Delete any STALE port file left behind by a prior dead daemon BEFORE
+  # launching. The readiness wait below keys off port-file *existence*, so a
+  # leftover port file from a crashed/killed daemon makes the wait exit
+  # immediately and read the OLD (dead) port — the freshly launched daemon then
+  # never receives its event and runs "headless" (no key → cleartext, INACTIVE
+  # row, no heartbeat). Removing it forces the wait to block until THIS daemon
+  # writes its real port.
+  rm -f "$port_file"
+
+  log "INFO" "ensure_mcp_daemon: launching MCP server for root session $daemon_session_id (trigger session $session_id)"
+  # Same launch shape session-start.sh used: cd to plugin root (for .env),
+  # exec node so $! is the node PID, pass through tmux session + ENVIRONMENT.
+  (cd "$plugin_root" && exec env CODEVIBE_TMUX_SESSION="${CODEVIBE_TMUX_SESSION}" ENVIRONMENT="${ENVIRONMENT:-development}" node "$plugin_root/dist/server.js" "$daemon_session_id") >> "${CODEVIBE_TMPDIR}/codevibe-claude-mcp.log" 2>&1 &
+  local server_pid=$!
+  echo "$server_pid" > "$pid_file"
+  # (#638 G3) Child is launched but UNPUBLISHED (no port/mapping yet) — eligible for
+  # the owner-crash trap's identity-guarded reap until publish clears this.
+  CODEVIBE_ENSURE_CHILD_PID="$server_pid"
+
+  # HOLD THE LOCK THROUGH THE FULL COLD START. The daemon writes its port file
+  # only inside app.listen(), which runs AFTER start() awaits authenticate +
+  # registerDeviceEncryptionKey + orphan-sweep — all NETWORK calls. On the exact
+  # incident (woken Mac, slow/returning network) that can take far longer than a
+  # few seconds. If we released the lock at ~5s, a hook firing in the gap would
+  # find no live daemon (no mapping/port yet) and launch a DUPLICATE. So wait
+  # WHILE this daemon's PID is alive, up to ~60s, breaking the instant the port
+  # appears (→ write mapping, release lock) OR the PID dies (→ auth-fail death:
+  # give up immediately; do NOT keep waiting the full cap).
+  local waited2=0   # readiness cap is $max_wait (computed above)
+  while [ ! -f "$port_file" ] && ps -p "$server_pid" > /dev/null 2>&1 && [ $waited2 -lt $max_wait ]; do
+    sleep 0.5
+    waited2=$((waited2 + 1))
+  done
+
+  local rc=1 out_port=""
+  if [ -f "$port_file" ]; then
+    out_port=$(cat "$port_file")
+    log "INFO" "ensure_mcp_daemon: MCP server started (pid $server_pid, port $out_port)"
+    if [ -n "$mapping_file" ]; then
+      echo "{\"session\":\"$daemon_session_id\",\"port\":$out_port,\"pid\":$server_pid}" > "$mapping_file"
+    fi
+    # (#638 G3) PUBLISHED — the live daemon is now discoverable; it must never be
+    # reaped by the owner-crash trap.
+    CODEVIBE_ENSURE_CHILD_PID=""
+    rc=0
+  elif ! ps -p "$server_pid" > /dev/null 2>&1; then
+    log "ERROR" "ensure_mcp_daemon: MCP server died on startup (likely auth failure). Run 'codevibe login' first."
+  else
+    # (#638 F3) Cold-start cap elapsed and the port never appeared, but the launched
+    # PID is STILL ALIVE. Leaving it alive-and-UNMAPPED is the exact #638 duplicate
+    # bug: the next ensure finds no live mapping, relaunches, and now TWO daemons run
+    # for one session. A daemon that hasn't bound its port within the cap is not making
+    # progress, so TERMINATE + REAP it (identity-guarded) BEFORE releasing the lock —
+    # no orphan survives for a duplicate to race; a clean relaunch on the next ensure
+    # is correct. If the PID is no longer ours (died + PID reused mid-wait), do NOT
+    # kill a foreign process — just release and fail.
+    # (#638 G5) Identity is re-verified immediately before EVERY signal (TERM and
+    # the KILL escalation) inside the shared reap helper — the PID can die after
+    # SIGTERM and be recycled during the settle poll; without the re-check the
+    # kill -9 could hit an unrelated process. A foreign PID is logged + left alone.
+    log "WARN" "ensure_mcp_daemon: port not bound within cold-start cap; reaping stuck daemon pid $server_pid to avoid an orphan+duplicate"
+    _reap_codevibe_daemon_pid "$server_pid" "stuck cold-start (port never bound)"
+    CODEVIBE_ENSURE_CHILD_PID=""   # reaped (or intentionally left) — trap must not re-signal
+    # (#638 G5) ALWAYS clean the pidfile on the reap path — the daemon we launched is
+    # gone (reaped, or its PID was recycled to a foreign process), so the pidfile is
+    # provably stale either way; leaving it points later sweeps at a wrong PID.
+    rm -f "$pid_file"
+  fi
+
+  rmdir "$lock_dir" 2>/dev/null   # release the launch lock (held for the whole cold start)
+  trap - EXIT HUP INT TERM        # (#638 G3) lock released — clear the crash-cleanup trap
+  CODEVIBE_ENSURE_LOCK_DIR=""
+  CODEVIBE_ENSURE_CHILD_PID=""
+  CODEVIBE_ENSURE_PORT_FILE=""
+  CODEVIBE_ENSURE_MAPPING_FILE=""
+  CODEVIBE_ENSURE_SESSION_ID=""
+  [ $rc -eq 0 ] && echo "$out_port"
+  return $rc
+}
+
 # Send event to MCP server via HTTP POST
 # Usage: send_to_mcp <endpoint> <json_data> [session_id]
 send_to_mcp() {
@@ -95,28 +713,79 @@ send_to_mcp() {
   log "DEBUG" "Payload: $json_data"
 
   # Send HTTP POST request to MCP server
-  local response
-  local http_code
+  # (#638 G6) Bounded like the /health probe: a wedged-but-health-passing daemon
+  # (accepts TCP, never responds) must not hang the hook indefinitely — hooks block
+  # the agent UI. --connect-timeout 2 bounds connection establishment; --max-time 10
+  # bounds the whole POST (generous for a slow-network POST).
+  local response curl_exit http_code body
 
-  response=$(curl -s -w "\n%{http_code}" \
+  response=$(curl -s --connect-timeout 2 --max-time 10 -w "\n%{http_code}" \
     -X POST \
     -H "Content-Type: application/json" \
     -d "$json_data" \
     "$mcp_url/$endpoint" 2>&1)
+  curl_exit=$?
 
   http_code=$(echo "$response" | tail -n 1)
   # Use sed instead of head -n -1 for macOS compatibility
-  local body=$(echo "$response" | sed '$d')
+  body=$(echo "$response" | sed '$d')
 
-  if [ "$http_code" = "200" ]; then
+  # (#638 G6) Success requires BOTH curl exit 0 AND HTTP 200. A curl timeout
+  # (exit 28) can still report a 200 status line if headers arrived before the
+  # response wedged — that is a TRANSPORT failure (delivery unconfirmed), not a
+  # success and not an app failure.
+  if [ "$curl_exit" -eq 0 ] && [ "$http_code" = "200" ]; then
     log "INFO" "Successfully sent to MCP server (HTTP $http_code)"
     log "DEBUG" "Response: $body"
     return 0
-  else
-    log "ERROR" "Failed to send to MCP server (HTTP $http_code)"
-    log "ERROR" "Response: $body"
+  fi
+
+  # (#638) TRANSPORT failure = curl non-zero (incl. exit 28 timeout on a wedged
+  # daemon) OR HTTP 000 (connection refused / no response = dead daemon). This is
+  # the Mac-sleep-killed-the-daemon case: on wake the port file points at a dead
+  # port. Relaunch the daemon ONCE and retry the POST once (one relaunch max, no
+  # loops). NOT for app 4xx/5xx — the daemon is alive and rejected the request;
+  # relaunching wouldn't help.
+  if { [ "$curl_exit" -ne 0 ] || [ "$http_code" = "000" ]; } && [ -n "$session_id" ]; then
+    log "WARN" "Transport failure to MCP server (curl exit $curl_exit, HTTP $http_code) — relaunching daemon and retrying once"
+    # (#638 H2) Pass the port that just transport-failed as the EXCLUDED port so
+    # ensure_mcp_daemon cannot hand the same wedged daemon back (its /health may
+    # still answer 200 while /event is wedged) — it reaps it and launches fresh.
+    local failed_port="${mcp_url##*:}"
+    # (#638 J1) Snapshot the failed daemon's IDENTITY (pid) NOW — at exclusion
+    # time, before ensure can wait on the instance lock — resolved the same way
+    # the H2 reap does (instance mapping first; session pidfile as the no-tmux
+    # fallback). Passing (port, pid) lets ensure tell THE wedged daemon from a
+    # healthy winner a concurrent hook relaunched on the SAME recycled port.
+    # Empty when no record names the failed port → port-only fallback in ensure.
+    local failed_pid
+    failed_pid=$(_resolve_mcp_daemon_pid_for_port "$session_id" "$failed_port")
+    local new_port
+    if new_port=$(ensure_mcp_daemon "$session_id" "$failed_port" "$failed_pid"); then
+      log "INFO" "Relaunched daemon on port $new_port, retrying POST /$endpoint"
+      response=$(curl -s --connect-timeout 2 --max-time 10 -w "\n%{http_code}" \
+        -X POST \
+        -H "Content-Type: application/json" \
+        -d "$json_data" \
+        "http://localhost:${new_port}/$endpoint" 2>&1)
+      curl_exit=$?
+      http_code=$(echo "$response" | tail -n 1)
+      body=$(echo "$response" | sed '$d')
+      if [ "$curl_exit" -eq 0 ] && [ "$http_code" = "200" ]; then
+        log "INFO" "Retry succeeded (HTTP $http_code)"
+        log "DEBUG" "Response: $body"
+        return 0
+      fi
+      log "WARN" "Retry after relaunch failed (curl exit $curl_exit, HTTP $http_code)"
+      return 1
+    fi
+    log "WARN" "Daemon relaunch failed; giving up on POST /$endpoint"
     return 1
   fi
+
+  log "ERROR" "Failed to send to MCP server (HTTP $http_code)"
+  log "ERROR" "Response: $body"
+  return 1
 }
 
 # Extract field from JSON using grep/sed (simple alternative to jq)
@@ -154,6 +823,17 @@ export CODEVIBE_TMPDIR
 export -f log
 export -f get_mcp_server_url
 export -f read_json_input
+export -f _claude_root_owner_file
+export -f _read_claude_root_session
+export -f record_claude_root_session
+export -f is_codevibe_daemon
+export -f _probe_claude_health
+export -f _reuse_live_mcp_daemon
+export -f _resolve_mcp_daemon_pid_for_port
+export -f _mcp_candidate_is_excluded
+export -f _reap_codevibe_daemon_pid
+export -f _codevibe_ensure_lock_cleanup
+export -f ensure_mcp_daemon
 export -f send_to_mcp
 export -f extract_field
 export -f check_mcp_server