Investigate: Codex bridge launcher/request-file machinery may be redundant (hook fires on first turn, launcher=0, direct nohup launch connects)

[fujibee]

Summary

While debugging "restart didn't auto-launch the Codex bridge" (aggie-co, real machine, 2026-06-17), two observations contradict the documented launcher/request-file design and suggest that machinery may be redundant:

1. The SessionStart hook fires on the user's FIRST turn, not at TUI launch. A sentinel-gated trace in session-start.sh's codex block stayed empty after a fresh codex launch and only logged fired the instant the user typed a message. (This is the real cause of the "I restarted and nothing happened" reports — there is a launch→first-turn window with no bridge.)

2. When the hook fires, AGMSG_CODEX_BRIDGE_LAUNCHER is NOT inherited from codex-monitor.sh (trace shows launcher=0). So the hook never takes the request-file path — it takes the direct-launch fallback (nohup codex-bridge.js … from inside the hook), and that path works: socket connect + thread resume + turn delivery all succeed. No request file is ever written; the launcher process (codex-bridge-launcher.sh) runs but sits idle.

Why this contradicts the design

The launcher + request-file rendezvous exists specifically to dodge an EPERM that was reproduced on this same machine: a direct Unix-socket connect from the sandboxed hook returned EPERM, so the hook was made to only write a request file and an out-of-sandbox launcher owned the connection. (Documented as a hard dead-end: "launching the bridge directly from the hook → socket EPERM".)

Yet the direct path connected fine here. Most likely reconciliation: the original EPERM came from an in-process synchronous connect inside the hook, whereas the current code nohups a detached child, which escapes the sandbox and connects without EPERM. If that holds, the launcher/request-file layer is dead weight.

Open questions / what to verify

• Is launcher=0 (env not propagated from codex-monitor.sh to the hook) expected Codex behavior? If so, the request-file path can never be triggered by the hook as written — meaning it has never actually run in the normal flow.
• Does the detached-child direct launch reliably escape the sandbox across Codex versions, or is the EPERM intermittent/version-specific? Controlled test: force the launcher path off, restart several times, watch for any EPERM in the bridge log.
• If direct launch is reliable: remove codex-bridge-launcher.sh + the request-file rendezvous + the AGMSG_CODEX_BRIDGE_LAUNCHER plumbing, and have the hook launch the detached bridge directly. Large simplification.

Do NOT rip it out yet

The launcher guards a reproduced EPERM; one contrary observation isn't enough to remove a safety net. Verify the EPERM premise first.

Related

#41 (Codex monitor bridge), #149 (no teardown on session end), #150 (one identity per project), #151 (enable-needs-restart). The first-turn-fire finding also means the user-facing docs should say "the bridge starts after your first message," which is being updated separately.

[fujibee]

Diagnostic trace patch (sentinel-gated)

The instrumentation used to prove the first-turn-fire / launcher=0 findings, kept here so the EPERM re-verification can re-apply it without re-deriving. Off by default; enable with touch run/.codex-hook-trace. Writes one line per hook decision to run/codex-bridge-hook.<projhash>.log (e.g. fired launcher=0 thread=…). Remove before GA.

diff --git a/scripts/session-start.sh b/scripts/session-start.sh
index acbbb2c..a9c3334 100755
--- a/scripts/session-start.sh
+++ b/scripts/session-start.sh
@@ -84,8 +84,22 @@ INNER_EOF
 # launcher start the bridge — a hook-launched bridge cannot connect to the unix
 # socket from inside the Codex sandbox (#41).
 if [ "$TYPE" = "codex" ]; then
+  # Optional diagnostic trace for the bridge auto-launch path. Off by default;
+  # enable by `touch run/.codex-hook-trace`. Records why the hook exits early so
+  # a non-deterministic "restart did not auto-launch the bridge" can be caught in
+  # the act. Independent of env propagation (#41 follow-up). Remove before GA.
+  _codex_hook_project_hash=$(printf '%s' "$PROJECT" | shasum | awk '{print $1}')
+  _codex_hook_trace() {
+    [ -f "$RUN_DIR/.codex-hook-trace" ] || return 0
+    printf '%s\t%s\tlauncher=%s\tthread=%s\tapp_server=%s\tpairs=%s\n' \
+      "$(date '+%Y-%m-%dT%H:%M:%S')" "$1" \
+      "${AGMSG_CODEX_BRIDGE_LAUNCHER:-0}" "${thread_id:-}" "${app_server:-}" \
+      "$(printf '%s\n' "$PAIRS" | awk 'NF>=2{c++} END{print c+0}')" \
+      >> "$RUN_DIR/codex-bridge-hook.$_codex_hook_project_hash.log" 2>/dev/null || true
+  }
+  _codex_hook_trace fired
   thread_id="$(agmsg_resolve_codex_thread "$PROJECT")"
-  [ -n "$thread_id" ] || exit 0
+  [ -n "$thread_id" ] || { _codex_hook_trace 'exit:no-thread'; exit 0; }
   app_server="${AGMSG_CODEX_BRIDGE_APP_SERVER:-}"
   if [ -z "$app_server" ]; then
     agent_pid=$(agmsg_agent_pid "$TYPE" 2>/dev/null || true)
@@ -103,13 +117,13 @@ if [ "$TYPE" = "codex" ]; then
       app_server="unix://$socket_path"
     fi
   fi
-  [ -n "$app_server" ] || exit 0
+  [ -n "$app_server" ] || { _codex_hook_trace 'exit:no-app-server'; exit 0; }
 
   pair_count=$(printf '%s\n' "$PAIRS" | awk 'NF >= 2 { c++ } END { print c + 0 }')
-  [ "$pair_count" = "1" ] || exit 0
+  [ "$pair_count" = "1" ] || { _codex_hook_trace "exit:pair-count=$pair_count"; exit 0; }
   team=$(printf '%s\n' "$PAIRS" | awk 'NF >= 2 { print $1; exit }')
   name=$(printf '%s\n' "$PAIRS" | awk 'NF >= 2 { print $2; exit }')
-  [ -n "$team" ] && [ -n "$name" ] || exit 0
+  [ -n "$team" ] && [ -n "$name" ] || { _codex_hook_trace 'exit:no-team-name'; exit 0; }
 
   if [ "${AGMSG_CODEX_BRIDGE_LAUNCHER:-}" = "1" ]; then
     project_hash=$(printf '%s' "$PROJECT" | shasum | awk '{print $1}')
@@ -119,6 +133,7 @@ if [ "$TYPE" = "codex" ]; then
     printf '%s\t%s\t%s\t%s\t%s\n' \
       "$TYPE" "$team" "$name" "$thread_id" "$app_server" > "$tmp_request"
     mv "$tmp_request" "$request_file"
+    _codex_hook_trace "wrote-request:$team/$name"
     exit 0
   fi