The control socket reference sends macOS readers to $XDG_RUNTIME_DIR/meshbench.sock, which is never where it is on a Mac

[A13xB0]

Found during the #318 pre-release pass on v0.0.10, macOS 26.3, Apple silicon, installed from the release dmg. First pass of that issue on a Mac.

Three pages tell a macOS reader the control socket is somewhere it has never been.

reference-control.md — "Where it listens, and how to connect"

| Linux, macOS | a unix socket at `$XDG_RUNTIME_DIR/meshbench.sock` | the file's own permissions, 0600 |
| Windows      | TCP on loopback, on a port the workbench is given when it starts | a token … |

XDG_RUNTIME_DIR is a freedesktop variable. macOS does not set it, and nothing on a Mac does. Following the row literally gives /meshbench.sock, which does not exist and never will, with no hint as to why.

What actually happens is in internal/app/control/address.go:173-197, and the code says so in a comment:

// Linux keeps exactly the path it has always had …
if dir := os.Getenv("XDG_RUNTIME_DIR"); dir != "" {
    p := filepath.Join(dir, "meshbench.sock")
    return Address{Kind: Unix, Addr: p}, checkUnixPath(p)
}
// Everywhere else, a per-user directory the OS already defines … On macOS
// this is ~/Library/Caches, short enough to stay inside sun_path where
// $TMPDIR would not be.
dir, _ := os.UserCacheDir()
dir = filepath.Join(dir, "meshbench")
…
p := filepath.Join(dir, "control.sock")

So on macOS it is:

~/Library/Caches/meshbench/control.sock

Confirmed live on this machine — that file is there and answers, and it is where the workbench put it with no -control-socket given.

Two things differ, not one. The directory and the filename: meshbench.sock under XDG_RUNTIME_DIR, control.sock under the cache directory. Someone who works out the directory from first principles still guesses the wrong name.

It is also worth saying that the Linux row is conditional rather than absolute — a Linux session with no XDG_RUNTIME_DIR set takes the same fallback, so ~/.cache/meshbench/control.sock is a real Linux address too.

architecture.md:170 and settings.md:112

Both repeat the same sentence:

The application listens on $XDG_RUNTIME_DIR/meshbench.sock, newline …
let agents drive this workbench — opens the control socket at $XDG_RUNTIME_DIR/meshbench.sock

Same correction.

Related, and the reason this is worth doing now

This is the shape #612 closed for Windows: the page described one platform and stopped. Windows was added; macOS was left on the Linux row it was already sharing, which reads as covered and is not. A Mac reader is worse off than a Windows one was, because the Windows row was visibly absent while this one is present and wrong.

Suggested wording

	address	authorisation
Linux	$XDG_RUNTIME_DIR/meshbench.sock, or ~/.cache/meshbench/control.sock where that variable is unset	the file's own permissions, 0600
macOS	~/Library/Caches/meshbench/control.sock	the file's own permissions, 0600
Windows	TCP on loopback …	a token, sent as the first line

-control-socket and MESHBENCH_CONTROL_SOCKET override all three, which the CLI reference already says and this page could point at.

One more, on the same page

agent-skills.md publishes the meshbench-driving skill, whose text carries the same $XDG_RUNTIME_DIR/meshbench.sock sentence — and, separately, says "session.describe lists every verb". It does not: it answers nodes, seed, now_ms, playing, exactly as scripting-verbs.md documents. session.verbs is the one that lists verbs. Filed against the source of that skill rather than here, but noting it because it reaches readers through this site.