Merge pull request 'fix(bridge): strip NODE_OPTIONS --inspect before spawning claude/gemini' (#5) from fix/strip-inspect-from-spawn-env into main

claude-code and gemini-cli are both Node binaries. When the parent
gateway is launched with `NODE_OPTIONS=--inspect=127.0.0.1:9229` (for
debugging), spawn(child).env = {...process.env} propagates the flag into
the child. The child Node then tries to bind the same inspector port,
fails EADDRINUSE, and exits SILENTLY (no stdout, no stderr).

Bridge sees an empty stream and reports `claude did not return a
session_id` with an empty stderr summary — extremely opaque diagnostic
that took non-trivial digging to root-cause.

Sanitize NODE_OPTIONS before spawn: keep everything except
`--inspect*` / `--inspect-brk*` / `--debug*`. Operators that legitimately
need other NODE_OPTIONS values (e.g. `--max-old-space-size`) keep them.

Verified end-user repro on prod-t2 2026-05-31: with
`Environment=NODE_OPTIONS=--inspect=127.0.0.1:9229` in the gateway
systemd drop-in, `claude -p "hi" --output-format stream-json --verbose`
spawned from the bridge returned ZERO bytes; running the exact same
command from a shell without the env var returned the full init →
assistant → result stream in ~6s. Surfaced recruiting developer1
(Cody, contractor-claude-bridge).

plugin/core/claude/sdk-adapter.ts

@@ -158,10 +158,29 @@ export async function* dispatchToClaude(
   // detached:true puts claude in its own process group. Claude's Bash tool
   // occasionally leaks shells/ssh that keep claude alive past end-of-turn; when
   // that happens we SIGKILL the whole group rather than wait forever.
+  // Sanitize NODE_OPTIONS before spawning. Claude Code is a Node CLI; if
+  // the parent gateway runs with `NODE_OPTIONS=--inspect=...:9229`, every
+  // child Node process — including claude — tries to bind the same inspector
+  // port, fails (EADDRINUSE), and exits SILENTLY (no stdout, no stderr).
+  // Bridge then sees an empty stream and reports `claude did not return a
+  // session_id` with no useful diagnostic. Strip any --inspect* /
+  // --inspect-brk* / --debug* flag from NODE_OPTIONS; keep everything else
+  // (e.g. --max-old-space-size) in case operators depend on it.
+  const childEnv: NodeJS.ProcessEnv = { ...process.env };
+  if (childEnv.NODE_OPTIONS) {
+    const filtered = childEnv.NODE_OPTIONS
+      .split(/\s+/)
+      .filter((tok) => tok && !tok.startsWith("--inspect") && !tok.startsWith("--debug"))
+      .join(" ")
+      .trim();
+    if (filtered) childEnv.NODE_OPTIONS = filtered;
+    else delete childEnv.NODE_OPTIONS;
+  }
+
   const child = spawn("claude", args, {
     cwd: workspace,
     stdio: ["ignore", "pipe", "pipe"],
-    env: { ...process.env },
+    env: childEnv,
     detached: true,
   });
 

plugin/core/gemini/sdk-adapter.ts

@@ -156,10 +156,24 @@ export async function* dispatchToGemini(
     args.push("--resume", resumeSessionId);
   }
 
+  // Sanitize NODE_OPTIONS before spawning — same reason as the claude
+  // adapter: gemini-cli is a Node binary; inheriting a parent
+  // `NODE_OPTIONS=--inspect=...:9229` makes every child silently EADDRINUSE.
+  const childEnv: NodeJS.ProcessEnv = { ...process.env };
+  if (childEnv.NODE_OPTIONS) {
+    const filtered = childEnv.NODE_OPTIONS
+      .split(/\s+/)
+      .filter((tok) => tok && !tok.startsWith("--inspect") && !tok.startsWith("--debug"))
+      .join(" ")
+      .trim();
+    if (filtered) childEnv.NODE_OPTIONS = filtered;
+    else delete childEnv.NODE_OPTIONS;
+  }
+
   const child = spawn("gemini", args, {
     cwd: workspace,
     stdio: ["ignore", "pipe", "pipe"],
-    env: { ...process.env },
+    env: childEnv,
   });
 
   const stderrLines: string[] = [];

plugin/web/input-filter.ts

@@ -61,6 +61,51 @@ function isRuntimeContextMessage(text: string): boolean {
   return INBOUND_META_SENTINELS.includes(firstLine);
 }
 
+/**
+ * Strip *prefixed* metadata blocks from a single user message body.
+ *
+ * Background: OpenClaw's older / canonical convention is to emit metadata
+ * envelopes (chat_id, sender, reply target, …) as SEPARATE user-role
+ * messages folded into the openai-completions request right after the real
+ * one. `extractLatestUserMessage` skips those separate messages whole.
+ *
+ * The Fabric channel plugin (Fabric.OpenclawPlugin) does not split: it
+ * passes the metadata blocks and the actual user content as ONE merged
+ * user-message body, separated by blank lines. Result: a Fabric inbound
+ * turn has a single user message whose first line matches a sentinel, so
+ * `isRuntimeContextMessage` returned true and the whole turn was dropped
+ * with "no user message found" (HTTP 400). Symptom: every contractor agent
+ * subscribed to a Fabric channel silently fails to reply.
+ *
+ * Strip leading sentinel-prefixed blocks (sentinel header + optional code
+ * fence + blank-line separator) until we hit a block whose first line is
+ * NOT a sentinel — that's the real prompt. Returns "" if the entire body
+ * is metadata-only (still a no-op turn, same as before).
+ */
+function stripPrefixedMetadataBlocks(raw: string): string {
+  // Split on blank-line block boundaries. Within a metadata block the JSON
+  // code fence has only single newlines, so it stays in the same chunk as
+  // its sentinel header.
+  const blocks = raw.split(/\n\n+/);
+  const kept: string[] = [];
+  let stillStripping = true;
+  for (const block of blocks) {
+    if (stillStripping) {
+      const trimmed = block.trimStart();
+      const firstLine = trimmed.split("\n", 1)[0].trim();
+      if (
+        INBOUND_META_SENTINELS.includes(firstLine) ||
+        trimmed.startsWith(LEGACY_RUNTIME_CONTEXT_MARKER)
+      ) {
+        continue; // drop this prefix block
+      }
+      stillStripping = false;
+    }
+    kept.push(block);
+  }
+  return kept.join("\n\n").trim();
+}
+
 /**
  * Extract the latest user-authored message from the OpenClaw request.
  *
@@ -85,7 +130,18 @@ export function extractLatestUserMessage(req: BridgeInboundRequest): string {
   for (let i = userMessages.length - 1; i >= 0; i -= 1) {
     const raw = messageText(userMessages[i]);
     if (!raw) continue;
-    if (isRuntimeContextMessage(raw)) continue;
+    // First try the separate-message convention (Discord/Telegram path): a
+    // user message whose entire body is one metadata envelope — skip whole.
+    if (isRuntimeContextMessage(raw)) {
+      // ...but also try inline-prefixed-metadata recovery (Fabric path):
+      // some channels splice metadata + real content into one body. Walk
+      // past leading sentinel blocks; if any non-metadata block follows,
+      // that's the prompt. If nothing follows, this turn really is pure
+      // metadata and we keep skipping.
+      const stripped = stripPrefixedMetadataBlocks(raw);
+      if (stripped) return stripOpenClawTimestampPrefix(stripped);
+      continue;
+    }
     return stripOpenClawTimestampPrefix(raw);
   }
   return "";

plugin/web/server.ts

@@ -596,14 +596,47 @@ export function createBridgeServer(config: BridgeServerConfig): http.Server {
           return;
         }
 
-        const execFn = (toolInstance as { execute: (id: string, args: unknown) => Promise<{ content?: Array<{ type: string; text?: string }> }> }).execute;
+        const execFn = (toolInstance as { execute: (id: string, args: unknown) => Promise<unknown> }).execute;
-        const toolResult = await execFn(randomUUID(), toolArgs);
+        const toolResultRaw = await execFn(randomUUID(), toolArgs);
 
-        // Extract text content from AgentToolResult
+        // Normalize the result shape. OpenClaw plugins return one of:
-        const text = (toolResult.content ?? [])
+        //   (a) AgentToolResult — { content: [{type:'text', text:'...'}, ...] }
-          .filter((c) => c.type === "text" && c.text)
+        //       used by tools that wrap via asContent() (e.g. all
-          .map((c) => c.text as string)
+        //       Dialectic.OpenclawPlugin tools).
-          .join("\n");
+        //   (b) raw JSON-able object — { ok:true, ...domain fields }
+        //       used by tools that return data directly (e.g. every
+        //       Fabric.OpenclawPlugin tool: fabric-channel-list,
+        //       fabric-guild-list, fabric-send-message, etc).
+        //   (c) null / undefined — fire-and-forget (rare).
+        //
+        // Pre-2026-05-24 the bridge ONLY handled shape (a); shape (b)
+        // silently returned "(no result)" to Claude Code (bug:
+        // fabric-channel-list and friends were unusable from contractor
+        // agents even though the tool actually ran successfully).
+        let text = "";
+        if (toolResultRaw == null) {
+          text = "";
+        } else if (
+          typeof toolResultRaw === "object" &&
+          Array.isArray((toolResultRaw as { content?: unknown }).content)
+        ) {
+          // Shape (a)
+          const content = (toolResultRaw as { content: Array<{ type: string; text?: string }> }).content;
+          text = content
+            .filter((c) => c.type === "text" && c.text)
+            .map((c) => c.text as string)
+            .join("\n");
+        } else if (typeof toolResultRaw === "string") {
+          text = toolResultRaw;
+        } else {
+          // Shape (b) — serialize the whole object as JSON. Claude Code
+          // is happy to parse JSON tool results.
+          try {
+            text = JSON.stringify(toolResultRaw);
+          } catch {
+            text = String(toolResultRaw);
+          }
+        }
 
         sendJson(res, 200, { result: text || "(no result)" });
       } catch (err) {