@quantiya/codevibe-codex-plugin 2.0.6 → 2.0.8

package/hooks/common.sh

@@ -87,40 +87,527 @@ read_json_input() {
   cat
 }
 
-send_to_server() {
-  local endpoint="$1"
-  local json_data="$2"
+# (#638) Ensure the Codex companion daemon is running for THIS tmux session;
+# echo its port on stdout. The daemon is normally launched by the private
+# libexec/companion-launcher (one `node dist/server.js` per tmux session, keyed on
+# CODEVIBE_CODEX_TMUX_SESSION). When it dies (Mac sleep + network drop → the daemon
+# stops heart-beating and exits), hook POSTs hit a dead port (HTTP 000) or find no
+# port file. This relaunches the daemon with the SAME launch shape the wrapper used
+# — matching its port-file model (${TMPDIR}/codevibe-codex-<tmux>.port) and its env
+# (CODEVIBE_CODEX_TMUX_SESSION + ENVIRONMENT, default production) — clearing any
+# stale port file first, then waits for the fresh port. Echoes the port and returns
+# 0 on success, non-zero on failure.
+# Helper: if the port file exists AND a CODEVIBE-CODEX daemon is listening on that
+# port, echo the port and return 0; else return 1. Codex has no PID mapping the
+# hook can read, so liveness is a GET /health probe — but we REQUIRE the response
+# body to carry the `"service":"codevibe-codex"` marker (#638 finding-2). Matching
+# ANY non-000 code would false-positive on a recycled ephemeral port grabbed by an
+# unrelated local HTTP server (which returns some other body / a 404), making us
+# reuse the wrong port and never relaunch the real daemon. Bounded via --max-time.
+# (#638 G5) True (0) iff PID is still a codevibe-codex daemon process (`ps -o
+# command=` match on node + codevibe-codex + server.js — covers the npm cache path
+# and the dev path). Codex's reap previously had NO identity guard: the launched
+# PID can die between SIGTERM and the SIGKILL escalation (there IS a sleep window)
+# and be recycled to an unrelated process — signaling it blind could kill a foreign
+# process. Mirror of the claude plugin's is_codevibe_daemon.
+is_codevibe_codex_daemon() {
+  local pid="$1"
+  local cmd
+  cmd=$(ps -o command= -p "$pid" 2>/dev/null)
+  case "$cmd" in
+    *node*codevibe-codex*server.js*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
 
-  local server_url
-  server_url=$(get_server_url)
-  if [ -z "$server_url" ]; then
-    log "ERROR" "No server URL — cannot send event"
+# (#638 G5/H2/H3) THE identity-guarded reap: TERM → bounded wait → identity
+# re-check → KILL → settle. Identity (is_codevibe_codex_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_codex_daemon_pid() {
+  local pid="$1" why="$2"
+  [ -n "$pid" ] || return 1
+  if ! is_codevibe_codex_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_codex_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_codex_daemon only. ensure_codex_daemon always runs
+# in a command-substitution subshell at its call site (send_to_server's
+# `$(ensure_codex_daemon)`), 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; just clear the marker and release the lock (the port file IS
+#      codex's full publication — there is no separate mapping). 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_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 → healthy;
+      # do NOT signal. Releasing the lock below finalizes the publication.
+      log "WARN" "ensure_codex_daemon: interrupted AFTER child published (pid $CODEVIBE_ENSURE_CHILD_PID, port $(cat "$CODEVIBE_ENSURE_PORT_FILE" 2>/dev/null)) — NOT signaling (#638 H3)"
+    else
+      log "WARN" "ensure_codex_daemon: interrupted while holding relaunch lock — reaping unpublished child pid $CODEVIBE_ENSURE_CHILD_PID (#638 H3 bounded reap)"
+      _reap_codevibe_codex_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=""
+}
+
+_reuse_live_codex_daemon() {
+  local port_file="$1" port body
+  [ -f "$port_file" ] || return 1
+  port=$(cat "$port_file" 2>/dev/null)
+  [ -n "$port" ] || return 1
+  body=$(curl -s --max-time 2 "http://localhost:${port}/health" 2>/dev/null)
+  # (#638 F8) Require a TOP-LEVEL `.service == "codevibe-codex"` parsed with jq, NOT a
+  # substring match. A substring match false-positives on a foreign body that merely
+  # CONTAINS or NESTS the marker text — e.g. {"data":{"service":"codevibe-codex"}} or a
+  # log line quoting it — which would make us reuse an unrelated server's recycled port
+  # and never relaunch the real daemon. jq -e exits non-zero on non-JSON / a missing or
+  # non-matching top-level field, so a dead port (empty body) and a foreign body both
+  # correctly fail closed.
+  if echo "$body" | jq -e '.service == "codevibe-codex"' > /dev/null 2>&1; then
+    echo "$port"
+    return 0
+  fi
+  return 1
+}
+
+# (#638 J1) Echo the pid a live codevibe-codex daemon on <port> reports in its
+# /health body (top-level `.pid`, honored only when the `.service` marker matches
+# — a foreign server lying about `pid` is ignored). One bounded probe. Echoes a
+# validated numeric pid (return 0) or nothing (return 1: dead port / foreign
+# server / marker-less legacy daemon).
+_codex_daemon_pid_on_port() {
+  local port="$1" pid
+  [ -n "$port" ] || return 1
+  pid=$(curl -s --max-time 2 "http://localhost:${port}/health" 2>/dev/null \
+    | jq -r 'if .service == "codevibe-codex" then (.pid // empty) else empty end' 2>/dev/null)
+  case "$pid" in
+    ''|*[!0-9]*) return 1 ;;
+  esac
+  echo "$pid"
+}
+
+# (#638 J1) True (0) iff the reuse candidate that just passed
+# _reuse_live_codex_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_codex_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 (its own /health `.pid`, bounded probe) to match too.
+# With no exclude_pid (the failed daemon's /health was already dead 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.
+# Usage: _codex_candidate_is_excluded <cand_port> <exclude_port> <exclude_pid>
+_codex_candidate_is_excluded() {
+  local cand_port="$1" exclude_port="$2" exclude_pid="$3"
+  [ -n "$exclude_port" ] || return 1
+  [ "$cand_port" = "$exclude_port" ] || return 1
+  [ -n "$exclude_pid" ] || return 0          # port-only fallback (no snapshot identity)
+  local cand_pid
+  cand_pid=$(_codex_daemon_pid_on_port "$cand_port")
+  [ -n "$cand_pid" ] || return 0             # candidate pid unknowable → conservative port-only
+  [ "$cand_pid" = "$exclude_pid" ]
+}
+
+ensure_codex_daemon() {
+  # (#638 H2) Optional: a port KNOWN-BAD for /event delivery (send_to_server's
+  # POST timed out / transport-failed against it). The reuse fast path verifies
+  # /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 (PID from
+  # its own /health body, then is_codevibe_codex_daemon-verified), and launch
+  # exactly once. Only send_to_server's transport-failure retry passes this.
+  local exclude_port="$1"
+  # (#638 J1) Optional: the wedged daemon's pid, SNAPSHOTTED by send_to_server at
+  # exclusion time (one bounded /health `.pid` probe right after the POST
+  # transport-failed — probing at reap time instead would be the WRONG moment:
+  # by then the port may already be a concurrent hook's fresh winner). Port alone
+  # is NOT identity — a 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 the failed daemon's /health was already dead (pid
+  # unknowable) → port-only fallback (pre-J1 behavior; reap stays is_codevibe-
+  # guarded).
+  local exclude_pid="$2"
+  local tmux_session="${CODEVIBE_CODEX_TMUX_SESSION:-}"
+  if [ -z "$tmux_session" ]; then
+    log "ERROR" "ensure_codex_daemon: CODEVIBE_CODEX_TMUX_SESSION unset — cannot relaunch"
     return 1
   fi
 
-  log "DEBUG" "POST $server_url/$endpoint"
+  # Plugin dir = parent of the hooks dir that DEFINES this function (common.sh).
+  local hooks_dir plugin_dir
+  hooks_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  plugin_dir="$(cd "$hooks_dir/.." && pwd)"
+  if [ ! -f "$plugin_dir/dist/server.js" ]; then
+    log "ERROR" "ensure_codex_daemon: $plugin_dir/dist/server.js not found — cannot relaunch"
+    return 1
+  fi
 
-  local response
-  response=$(curl -s -w "\n%{http_code}" \
-    -X POST \
-    -H "Content-Type: application/json" \
-    -d "$json_data" \
-    "$server_url/$endpoint" 2>&1)
+  local port_file="${CODEVIBE_TMPDIR}/codevibe-codex-${tmux_session}.port"
+  # (#638 G3) Lock key VERIFIED against daemon scope: codex's port_file is already
+  # per-tmux-INSTANCE (codevibe-codex-<tmux>.port — one daemon per tmux session), so
+  # ${port_file}.lock is instance-scoped and matches the daemon being launched. No
+  # re-key needed (unlike claude, whose port file is session_id-scoped).
+  local lock_dir="${port_file}.lock"
 
-  local http_code
-  http_code=$(echo "$response" | tail -n 1)
+  # ── Fast path: reuse a live daemon (no lock needed) ──
+  local reuse
+  if reuse=$(_reuse_live_codex_daemon "$port_file"); then
+    if _codex_candidate_is_excluded "$reuse" "$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.
+      # (#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_codex_daemon: reuse candidate port $reuse is the excluded (wedged) daemon — skipping reuse, will reap + relaunch (#638 H2/J1)"
+    else
+      log "INFO" "ensure_codex_daemon: reusing live daemon (port $reuse)"
+      echo "$reuse"
+      return 0
+    fi
+  fi
+
+  # ── Serialize the LAUNCH (double-checked locking) ──
+  # Two near-simultaneous hooks that both hit a dead port would otherwise BOTH
+  # relaunch → two daemons on `app.listen(0)` (duplicate mobile events + double
+  # heartbeat, no daemon-side singleton). A mkdir-lock elects ONE launcher; the
+  # loser(s) wait briefly and reuse the winner's daemon via the /health probe.
+  # Reap a clearly-abandoned lock first. 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_codex_daemon: removing stale relaunch lock $lock_dir"
+    rmdir "$lock_dir" 2>/dev/null
+  fi
 
-  if [ "$http_code" = "200" ]; then
-    log "INFO" "Sent successfully (HTTP $http_code)"
+  # 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 (woken Mac + returning network → a ~60s cold start) makes the
+  # contender abandon at ~12s BEFORE the winner has published its port — its 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.
+  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))
+    # (#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_codex_daemon "$port_file"); then
+      if _codex_candidate_is_excluded "$reuse" "$exclude_port" "$exclude_pid"; then
+        continue   # wedged candidate — keep waiting for the lock to reap+relaunch
+      fi
+      log "INFO" "ensure_codex_daemon: reusing daemon launched concurrently (port $reuse)"
+      echo "$reuse"
+      return 0
+    fi
+  done
+  if [ $acquired -ne 1 ]; then
+    # (#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_codex_daemon "$port_file") \
+       && ! _codex_candidate_is_excluded "$reuse" "$exclude_port" "$exclude_pid"; then
+      echo "$reuse"; return 0
+    fi
+    log "WARN" "ensure_codex_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
+  # leave a healthy just-published daemon alone.
+  CODEVIBE_ENSURE_PORT_FILE="$port_file"
+  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_codex_daemon "$port_file") \
+     && ! _codex_candidate_is_excluded "$reuse" "$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=""
+    log "INFO" "ensure_codex_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.
+  # Codex has no instance-mapping/pid file the hook can read, so resolve the PID
+  # from the daemon's own /health body (top-level `.pid`, only when the marker
+  # matches) and identity-reap it (TERM→wait→KILL, G5 discipline) — the command
+  # line re-check means a foreign server lying about `pid` is never signaled.
+  if [ -n "$exclude_port" ]; then
+    local wedged_pid wedged_src
+    if [ -n "$exclude_pid" ]; then
+      # (#638 J1) Use the pid the CALLER snapshotted right when the POST failed.
+      # Probing /health HERE would be the wrong moment: the wedged daemon may
+      # have died and a concurrent hook's fresh winner may now hold the SAME
+      # recycled port — a reap-time probe would resolve (and reap) the healthy
+      # winner. The identity-guarded reap still refuses a dead/foreign pid.
+      wedged_pid="$exclude_pid"
+      wedged_src="snapshot"
+    else
+      # (#638 J1) No snapshot (the failed daemon's /health was already dead at
+      # exclusion time — pid unknowable): port-only fallback, reap-time probe,
+      # pre-J1 behavior. The reap below is still is_codevibe-guarded.
+      wedged_pid=$(_codex_daemon_pid_on_port "$exclude_port")
+      wedged_src="reap-time /health"
+    fi
+    case "$wedged_pid" in
+      ''|*[!0-9]*)
+        log "WARN" "ensure_codex_daemon: excluded port $exclude_port has no discoverable daemon pid (/health absent or foreign) — relaunching without reap (#638 H2)"
+        ;;
+      *)
+        log "WARN" "ensure_codex_daemon: reaping wedged daemon pid $wedged_pid on excluded port $exclude_port (via $wedged_src) before relaunch (#638 H2)"
+        _reap_codevibe_codex_daemon_pid "$wedged_pid" "wedged /event on port $exclude_port"
+        ;;
+    esac
+  fi
+
+  # ── Launch (single cleanup point: rmdir at the end) ──
+  # Delete any STALE port file left by a prior dead daemon BEFORE relaunch — the
+  # readiness wait below keys off port-file existence, so a leftover would make it
+  # read the OLD dead port.
+  rm -f "$port_file"
+
+  log "INFO" "ensure_codex_daemon: relaunching Codex companion daemon (tmux $tmux_session)"
+  # Same launch shape as libexec/companion-launcher: cd to plugin dir, exec node so the
+  # backgrounded process is the node daemon (PPID=1, detached). The daemon derives
+  # its port-file path + tmux target from CODEVIBE_CODEX_TMUX_SESSION.
+  (cd "$plugin_dir" && exec env CODEVIBE_CODEX_TMUX_SESSION="$tmux_session" CODEVIBE_CODEX_DAEMON_RECOVERY=1 ENVIRONMENT="${ENVIRONMENT:-production}" node "$plugin_dir/dist/server.js") >> "${CODEVIBE_TMPDIR}/codevibe-codex-mcp.log" 2>&1 &
+  local server_pid=$!   # capture so we can hold the lock while the daemon cold-starts
+  # (#638 G3) Child is launched but UNPUBLISHED (no port 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). On the incident
+  # (woken Mac, slow/returning network) that can far exceed a few seconds; if we
+  # released the lock early a hook firing in the gap would find the port file
+  # still absent (we rm'd it) and launch a DUPLICATE. Wait WHILE the daemon PID
+  # is alive, up to ~60s, breaking the instant the port appears OR the PID dies
+  # (→ auth-fail death: give up immediately; do NOT wait 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" 2>/dev/null)
+    if [ -n "$out_port" ]; then
+      log "INFO" "ensure_codex_daemon: daemon ready on port $out_port"
+      # (#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
+    fi
+  fi
+  if [ $rc -ne 0 ]; then
+    if ! ps -p "$server_pid" > /dev/null 2>&1; then
+      log "ERROR" "ensure_codex_daemon: daemon died on startup (likely auth failure)"
+    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 #638 duplicate bug: the
+      # next hook's ensure finds no live daemon, relaunches, and now TWO daemons run for
+      # one tmux session. A daemon that hasn't bound its port within the cap is not making
+      # progress, so TERMINATE + REAP it BEFORE releasing the lock — no orphan survives for
+      # a duplicate to race; a clean relaunch on the next ensure is correct.
+      # (#638 G5) The old "continuously-alive so identity-safe" claim was WRONG for the
+      # KILL escalation: there IS a sleep window between the SIGTERM and the SIGKILL in
+      # which the PID can die and be recycled to an unrelated process. The shared reap
+      # helper re-verifies identity (is_codevibe_codex_daemon) immediately before EVERY
+      # signal — TERM and KILL; a foreign PID is logged + left alone.
+      log "WARN" "ensure_codex_daemon: port not bound within cold-start cap; reaping stuck daemon pid $server_pid to avoid an orphan+duplicate"
+      _reap_codevibe_codex_daemon_pid "$server_pid" "stuck cold-start (port never bound)"
+      CODEVIBE_ENSURE_CHILD_PID=""   # reaped (or intentionally left) — trap must not re-signal
+    fi
+  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=""
+  [ $rc -eq 0 ] && echo "$out_port"
+  return $rc
+}
+
+send_to_server() {
+  local endpoint="$1"
+  local json_data="$2"
+
+  local server_url curl_exit http_code response
+  server_url=$(get_server_url)
+
+  if [ -n "$server_url" ]; then
+    log "DEBUG" "POST $server_url/$endpoint"
+    # (#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).
+    response=$(curl -s --connect-timeout 2 --max-time 10 -w "\n%{http_code}" \
+      -X POST \
+      -H "Content-Type: application/json" \
+      -d "$json_data" \
+      "$server_url/$endpoint" 2>&1)
+    curl_exit=$?
+    http_code=$(echo "$response" | tail -n 1)
+    # (#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,
+    # eligible for the one relaunch+retry below), not a success or app failure.
+    if [ "$curl_exit" -eq 0 ] && [ "$http_code" = "200" ]; then
+      log "INFO" "Sent successfully (HTTP $http_code)"
+      return 0
+    fi
   else
-    log "ERROR" "Failed (HTTP $http_code)"
+    # No port file at all = dead/absent daemon (the wrapper removes the port file
+    # on exit). Treat as a transport failure so the relaunch path below fires.
+    curl_exit=1
+    http_code="000"
+    log "WARN" "No server URL (port file missing) — will attempt daemon relaunch"
+  fi
+
+  # (#638) TRANSPORT failure = curl non-zero OR HTTP 000 (dead daemon / missing
+  # port file). 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" ]; then
+    log "WARN" "Transport failure to Codex daemon (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_codex_daemon cannot hand the same wedged daemon back (its /health
+    # may still answer 200 while /event is wedged) — it reaps it and launches
+    # fresh. Empty when there was no port file at all (nothing to exclude).
+    local failed_port=""
+    [ -n "$server_url" ] && failed_port="${server_url##*:}"
+    # (#638 J1) Snapshot the wedged daemon's IDENTITY (pid) NOW — one bounded
+    # /health `.pid` probe right after the transport failure, BEFORE calling
+    # ensure (which may wait on the lock while a concurrent hook reaps +
+    # relaunches on the SAME recycled port). Passing (port, pid) lets ensure
+    # tell THE wedged daemon from that healthy winner. Empty when /health is
+    # dead too (daemon fully dead — pid unknowable) → port-only fallback.
+    local failed_pid=""
+    [ -n "$failed_port" ] && failed_pid=$(_codex_daemon_pid_on_port "$failed_port")
+    local new_port retry
+    if new_port=$(ensure_codex_daemon "$failed_port" "$failed_pid"); then
+      log "INFO" "Relaunched Codex daemon on port $new_port, retrying POST /$endpoint"
+      retry=$(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 "$retry" | tail -n 1)
+      if [ "$curl_exit" -eq 0 ] && [ "$http_code" = "200" ]; then
+        log "INFO" "Retry succeeded (HTTP $http_code)"
+        return 0
+      fi
+      log "WARN" "Retry after relaunch failed (curl exit $curl_exit, HTTP $http_code)"
+      return 1
+    fi
+    log "WARN" "Codex daemon relaunch failed; giving up on POST /$endpoint"
     return 1
   fi
+
+  log "ERROR" "Failed (HTTP $http_code)"
+  return 1
 }
 
 export CODEVIBE_TMPDIR
 export -f log
 export -f get_server_url
 export -f read_json_input
+export -f is_codevibe_codex_daemon
+export -f _reap_codevibe_codex_daemon_pid
+export -f _codevibe_ensure_lock_cleanup
+export -f _reuse_live_codex_daemon
+export -f _codex_daemon_pid_on_port
+export -f _codex_candidate_is_excluded
+export -f ensure_codex_daemon
 export -f send_to_server