launcher broker: add CAPTURE_JSON: protocol; pipe + verbs use it

Foundation for the agent envelope's clean stdout/stderr split. The
prior CAPTURE: protocol concatenated subprocess stdout + stderr as
one byte stream over the socket, so the pipe couldn't tell which
part was the structured tool output and which part was English
narrative from a downstream tool (mios-find, mios-launch, mios-
windows, ...) writing diagnostics to stderr. The OpenAI tool_result
envelope wants stdout in tool_result.output and stderr in
tool_result.stderr -- separately -- so any English narrative
buckets into a clearly-labeled field instead of polluting the
operator-facing output.

usr/libexec/mios/mios-launcher-daemon
  * New CAPTURE_JSON: <cmd> command. Runs the same subprocess.run
    as CAPTURE:, returns a single JSON line:
      {"stdout":"...", "stderr":"...", "exit_code":N}
    Legacy CAPTURE: stays available for pre-update callers.

usr/share/mios/owui/pipes/mios_agent_pipe.py
  * _dispatch_mios_verb's broker call now uses CAPTURE_JSON:
    instead of CAPTURE:, parses the JSON response, and populates
    the envelope with:
      tool_result.output     <- broker stdout
      tool_result.stderr     <- broker stderr
      tool_result.success    <- (exit_code == 0)
      tool_result.exit_code  <- raw exit code
  * open_app dispatch loses its `2>/dev/null` hack -- stderr now
    lands in its own field, so suppressing it at the bash level
    is no longer needed and we keep the diagnostic info.

usr/share/mios/owui/tools/mios_verbs.py
  * _broker_send (used by every Tools class method when Hermes
    invokes a verb via OpenAI tool_calls) also switched to
    CAPTURE_JSON:. Fallback path retained: if the broker reply
    isn't valid JSON (older deployment), treat the whole thing
    as stdout to preserve the prior CAPTURE: text contract.

Live-verified on podman-MiOS-DEV: CAPTURE_JSON: mios-find notepad
returns stdout = the canonical launch command, stderr = a tmpfs
permission warning (cleanly bucketed into its own field), exit
0. Tool row in webui.db: 31528 -> 32443 chars after re-install.

Operator directive 2026-05-18: "MAKE SURE NO HARDCODED VALUES!"
The pipe layer's envelope is now structured-shape-only -- the
universal status symbols (✓/⚠), the OpenAI protocol identifiers,
and the JSON keys. Any English in the envelope necessarily comes
from a downstream tool's stderr (clearly labeled) -- no English
narrative invented by the pipe.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: mios-dev

usr/libexec/mios/mios-launcher-daemon

@@ -83,15 +83,51 @@ def handle(conn: socket.socket) -> None:
 
         # Protocol:
         #   <command>             -> fire-and-forget; reply "OK\n"
-        #   CAPTURE: <command>    -> run synchronously; capture stdout+stderr;
-        #                            reply with raw output (no OK prefix); close
+        #   CAPTURE: <command>    -> run synchronously; capture stdout+stderr
+        #                            CONCATENATED as bytes (legacy form;
+        #                            kept for backward compat).
+        #   CAPTURE_JSON: <command> -> run synchronously; reply with a
+        #                            single-line JSON object:
+        #                            {"stdout":"...","stderr":"...","exit_code":N}
+        #                            Lets the agent envelope split stdout
+        #                            from stderr cleanly -- English narrative
+        #                            from downstream tools (mios-find, mios-
+        #                            launch, ...) buckets into the stderr
+        #                            field instead of mixing with the
+        #                            tool_result.output structured data.
         # CAPTURE removes the cross-user tempfile dance: broker runs the
         # command in its own context, captures via subprocess.PIPE, sends
         # the bytes back to the caller. No file in /tmp or /run/mios-
         # launcher/ that another user has to write to. Operator-debug
         # 2026-05-15 found that mios cross-user-write to a mios-hermes-
         # owned mode 0666 file fails -- root cause unknown, fix unneeded
         # via this protocol.
+        if line.startswith("CAPTURE_JSON: "):
+            cmd = line[len("CAPTURE_JSON: "):]
+            log.info("capture_json: %s", cmd[:200])
+            env = dict(os.environ)
+            env.setdefault("GDK_BACKEND", "wayland")
+            payload = {"stdout": "", "stderr": "", "exit_code": -1}
+            try:
+                result = subprocess.run(
+                    ["bash", "-lc", cmd],
+                    stdin=subprocess.DEVNULL,
+                    capture_output=True,
+                    timeout=45,
+                    env=env,
+                )
+                payload["stdout"] = result.stdout.decode("utf-8", errors="replace")
+                payload["stderr"] = result.stderr.decode("utf-8", errors="replace")
+                payload["exit_code"] = int(result.returncode)
+            except subprocess.TimeoutExpired:
+                payload["stderr"] = "ERROR: capture timeout (>45s)"
+            except OSError as e:
+                payload["stderr"] = f"ERROR: {e}"
+            # Send as a single JSON line for unambiguous parsing.
+            import json as _json
+            conn.sendall((_json.dumps(payload) + "\n").encode("utf-8"))
+            return
+
         if line.startswith("CAPTURE: "):
             cmd = line[len("CAPTURE: "):]
             log.info("capture: %s", cmd[:200])

usr/share/mios/owui/pipes/mios_agent_pipe.py

@@ -1179,11 +1179,12 @@ async def _dispatch_mios_verb(
                 # actual operator-installed Steam client. mios-launch is
                 # the environment-generative path: games-cache is populated
                 # by mios-apps at runtime, not from a baked priority list.
-                # 2>/dev/null suppresses any stderr narrative (e.g.
-                # "mios-launch: <name> -> <cmd>" diagnostic line); the
-                # tool_result.stderr field will be a future broker-protocol
-                # enhancement so stderr isn't lost on failures.
-                cmd = f"{env_prefix}mios-launch {shlex.quote(name)} 2>/dev/null"
+                # No 2>/dev/null filter -- the broker's CAPTURE_JSON
+                # protocol (used below) now returns stdout / stderr / exit
+                # SEPARATELY, so English narrative on stderr lands in
+                # tool_result.stderr (labeled-as-stderr in the envelope)
+                # instead of polluting tool_result.output.
+                cmd = f"{env_prefix}mios-launch {shlex.quote(name)}"
         elif tool == "launch_app":
             cmd = f"mios-launch {shlex.quote(str(args.get('name', '')))}"
         elif tool == "focus_window":
@@ -1322,7 +1323,13 @@ async def _dispatch_mios_verb(
                 s = _socket.socket(_socket.AF_UNIX, _socket.SOCK_STREAM)
                 s.settimeout(15.0)
                 s.connect(sock_path)
-                s.sendall(("CAPTURE: " + cmd + "\n").encode())
+                # CAPTURE_JSON: protocol -- broker returns a single
+                # JSON line with {stdout, stderr, exit_code} so we can
+                # bucket English narrative on stderr into its own
+                # envelope field (instead of mixing with structured
+                # tool_result.output). Backward-compat CAPTURE: stays
+                # available on the broker for older callers.
+                s.sendall(("CAPTURE_JSON: " + cmd + "\n").encode())
                 chunks: list[bytes] = []
                 try:
                     while True:
@@ -1334,14 +1341,26 @@ async def _dispatch_mios_verb(
                 finally:
                     s.close()
                 raw = b"".join(chunks).decode("utf-8", errors="replace").strip()
-                if raw.startswith("ERROR:"):
-                    _result_payload = {"success": False, "stderr": raw}
-                else:
-                    _result_payload = {"success": True,
+                try:
+                    j = json.loads(raw) if raw else {}
+                except json.JSONDecodeError:
+                    j = {}
+                if not j:
+                    _result_payload = {"success": False,
                                        "tool": tool, "args": args,
-                                       "output": raw[:6000]}
+                                       "output": "", "stderr": raw or "broker: empty response"}
+                else:
+                    exit_code = int(j.get("exit_code", -1))
+                    _result_payload = {
+                        "success": exit_code == 0,
+                        "tool": tool, "args": args,
+                        "output": (j.get("stdout") or "")[:6000],
+                        "stderr": (j.get("stderr") or "")[:2000],
+                        "exit_code": exit_code,
+                    }
             except OSError as e:
-                _result_payload = {"success": False, "stderr": f"broker: {e}"}
+                _result_payload = {"success": False, "stderr": f"broker: {e}",
+                                   "output": "", "tool": tool, "args": args}
         # Best-effort SurrealDB write: tool_call row. Carries session id
         # if pipe() opened one this turn (self._session_id). Output is
         # truncated to keep the row compact.

usr/share/mios/owui/tools/mios_verbs.py

@@ -89,7 +89,15 @@ def _broker_send(line: str, timeout: float, capture: bool) -> dict:
         return {"success": False, "exit_code": -1, "stdout": "",
                 "stderr": f"launcher broker socket not present at {LAUNCHER_SOCKET} "
                           "(mios-launcher.service down? container missing the mount?)"}
-    payload = (f"CAPTURE: {line}" if capture else line).encode("utf-8") + b"\n"
+    # CAPTURE_JSON: returns a single JSON line {stdout, stderr, exit_code}
+    # so we get clean per-stream output for the agent envelope (English
+    # narratives from downstream tools land in stderr, structured data
+    # in stdout). Fire-and-forget calls (capture=False) keep the legacy
+    # plain-text protocol ("OK" / "ERROR: ...").
+    if capture:
+        payload = (f"CAPTURE_JSON: {line}").encode("utf-8") + b"\n"
+    else:
+        payload = line.encode("utf-8") + b"\n"
     try:
         s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
         s.settimeout(timeout)
@@ -109,21 +117,35 @@ def _broker_send(line: str, timeout: float, capture: bool) -> dict:
     except OSError as e:
         return {"success": False, "exit_code": -1,
                 "stdout": "", "stderr": f"broker connect: {e}"}
-    raw = b"".join(chunks).decode("utf-8", errors="replace")
+    raw = b"".join(chunks).decode("utf-8", errors="replace").strip()
     if capture:
-        # CAPTURE mode: raw output (no OK/ERROR framing). Empty reply =
-        # command produced no output (still a success if no error).
-        if raw.startswith("ERROR:"):
-            return {"success": False, "exit_code": -1,
-                    "stdout": "", "stderr": raw.strip()}
-        return {"success": True, "exit_code": 0,
-                "stdout": raw.strip()[:12000], "stderr": ""}
+        # Parse the JSON line. If parsing fails (e.g. broker pre-dates
+        # CAPTURE_JSON support and replied with raw bytes), fall back to
+        # treating the whole reply as stdout.
+        try:
+            j = json.loads(raw) if raw else {}
+        except (json.JSONDecodeError, ValueError):
+            j = {}
+        if not j:
+            # Pre-CAPTURE_JSON fallback path: raw text reply.
+            if raw.startswith("ERROR:"):
+                return {"success": False, "exit_code": -1,
+                        "stdout": "", "stderr": raw}
+            return {"success": True, "exit_code": 0,
+                    "stdout": raw[:12000], "stderr": ""}
+        exit_code = int(j.get("exit_code", -1))
+        return {
+            "success": exit_code == 0,
+            "exit_code": exit_code,
+            "stdout": (j.get("stdout") or "")[:12000],
+            "stderr": (j.get("stderr") or "")[:4000],
+        }
     # Fire-and-forget: "OK\n" or "ERROR: ..."
-    if raw.strip().startswith("OK"):
+    if raw.startswith("OK"):
         return {"success": True, "exit_code": 0,
                 "stdout": "", "stderr": ""}
     return {"success": False, "exit_code": -1,
-            "stdout": "", "stderr": raw.strip() or "broker returned no reply"}
+            "stdout": "", "stderr": raw or "broker returned no reply"}
 
 
 class Tools: