Summary

On macOS 2026.4.1, the mac-cli-host -> OpenClaw.app exec-host path can hang indefinitely even though the app is running, the socket is listening, and TCC permissions are already granted.

After tracing this end to end on April 2, 2026, the issue appears to be in the JSONL socket client used by the official CLI. The client writes one line but does not half-close the socket write side, while the app-side socket server reads with FileHandle.read(upToCount:) inside readLineFromHandle(...). In practice this can deadlock the request/response exchange.

Environment

• OpenClaw CLI: 2026.4.1 (da64a97)
• OpenClaw.app: 2026.4.1
• macOS: Darwin 25.4.0 / macOS 15.4
• Gateway topology: unchanged remote gateway + pc-steward -> exec(host=node) -> mac-cli-host
• mac-cli-host configured with OPENCLAW_NODE_EXEC_HOST=app

Symptoms

When the request goes through the macOS app exec host path:

• system.run via mac-cli-host times out
• static screenshot commands like screencapture -x ... time out
• the app is running and ~/.openclaw/exec-approvals.sock is listening
• direct app-node system.run can still work, which helps isolate the problem to the CLI -> app socket layer

Typical upstream-visible failure from the gateway side:

gateway timeout after 12000ms

Reproduction

1. Start OpenClaw.app.
2. Start mac-cli-host with OPENCLAW_NODE_EXEC_HOST=app.
3. Send a valid type: "exec" JSONL request to ~/.openclaw/exec-approvals.sock.
4. Keep the client socket write side open after writing the line.
5. Observe that the app does not reply and the caller times out.

I reproduced this with a direct socket probe and also through the real remote path:

• OCI -> pc-steward -> mac-cli-host -> OpenClaw.app

Root Cause Hypothesis

The server side in:

• apps/macos/Sources/OpenClaw/ExecApprovalsSocket.swift

uses readLineFromHandle(...), which calls FileHandle.read(upToCount:) in a loop.

The client side in:

• src/infra/jsonl-socket.ts

currently does:

client.connect(socketPath, () => {
  client.write(`${payload}\n`);
});

On my machine, that leaves the write side open and the server never completes the read/respond cycle. The same exact request immediately succeeds if the client half-closes after sending.

Minimal Fix That Worked Locally

Changing the client send from write(...) to end(...) fixed the issue immediately:

client.connect(socketPath, () => {
  client.end(`${payload}\n`);
});

Verification After Patch

After this one-line local patch, all of the following started working without changing the gateway topology:

• OCI -> pc-steward -> mac-cli-host -> system.run /usr/bin/uname -a
• OCI -> pc-steward -> mac-cli-host -> system.run /bin/cat /etc/hosts
• OCI -> pc-steward -> mac-cli-host -> system.run /usr/sbin/screencapture -x ...

The screenshot file was successfully created and visually verified.

Why I think this is upstream-safe

• This socket is JSONL request/response, not a long-lived bidirectional stream.
• The client only sends one request line and then waits for one response line.
• Half-closing the write side matches that protocol shape and avoids the deadlock.

Relevant Files

• docs/platforms/mac/xpc.md
• apps/macos/Sources/OpenClaw/ExecApprovalsSocket.swift
• src/infra/jsonl-socket.ts
• src/infra/exec-host.ts

If useful, I can also provide the exact direct-socket repro payload I used to confirm the difference between write() and shutdown(SHUT_WR) / end().