design(remote): choose the injection channel for remote sessions

[devsuitup]

Two candidate channels, both measured to exist.

The CLI messaging socket. Each live session declares
messagingSocketPath in its descriptor — a Unix socket, mode 600, confirmed
present on a declared host. The descriptor also carries peerProtocol: 1 and
peerFeatures (notify_idle, reply_across_default_dirs, artifact_yield),
so a versioned protocol exists. This channel is independent of any multiplexer
and of any PTY.

A Unix socket does not cross ssh on its own, and Unix-socket forwarding is not
dependable on the Windows client. But nc and python3 are present on the
host, so ssh <host> nc -U <socket> carries the conversation over one ordinary
connection. Measured: socket present, nc present.

A trigger file on the host. The existing trigger convention is already
consumed by a watcher running on the declared host, in the same JSON format the
local watcher uses. Writing one over ssh reuses remote-transport.js wholesale.
It requires that watcher to exist, which is not true of an arbitrary host.

The trigger schema carries no host field at all today —
sessionId, command, chain, wait, timeout_ms, expectedCwd — and
getPtyForSession (trigger-context.js:16-21) resolves targets from
activeSessions, a map of locally spawned PTYs. A remote id returns
"session not found" and cannot even be expressed.

Decide: which channel is primary, whether the protocol is documented enough to
speak, and how a result comes back. The socket is the multiplexer-independent
answer and should win unless speaking the protocol proves impractical.

Unverified: that the socket accepts a conversation from outside the session's
own process. That is the first thing to measure.

[devsuitup]

The blocking measurement is done, on a throwaway session created for it.

The socket accepts a connection from another process. Its descriptor gave
messagingSocketPath as /run/user/0/cc-socks/<pid>.sock, mode srw-------.
Connecting with nc -U from a plain shell held the connection open for the full
5 s timeout and exited 124 with an empty stderr — a refused or absent socket
would have failed immediately. So the channel is reachable from outside the
session's own process, and ssh <host> nc -U <socket> is a viable bridge that
needs no Unix-socket forwarding on the Windows client.

What is still unknown is the protocol. Sending a bare newline returned zero
bytes within 5 s. The descriptor advertises peerProtocol: 1 and
peerFeatures: ["notify_idle", "reply_across_default_dirs", "artifact_yield"],
so a framing exists and an empty line is simply not a valid message. Nothing
here says what a valid one looks like.

Note the socket path is not stable across hosts: a production session on the
same machine reported /var/tmp/<name>/cc-socks/<pid>.sock while the test
session reported /run/user/0/cc-socks/<pid>.sock. The path must always be read
from the descriptor, never derived.

Next step before choosing this channel over a trigger file: establish the frame.
Either from the CLI's own client, or by observing a legitimate exchange. Until
that is known, the trigger-file route stays the only one that can actually be
written today — at the cost of requiring a watcher on the host, which an
arbitrary host does not have.

[devsuitup]

The protocol is established, and a message has been delivered end to end against
a live remote session. This issue can be decided.

The protocol

NDJSON: one JSON object per line, UTF-8, terminated by \n, over a Unix socket
(POSIX) or a named pipe (Windows). Read from the shipped CLI bundle, v2.1.263.

Each connection is one-way. The server never writes back on the inbound
connection; a reply or a notice arrives as a new connection to the address
the message declared in from. A probe that connects and waits for an answer
sees nothing and times out — which is exactly what the earlier nc probe on
this issue observed, and it was not a failure.

Send a prompt:

{"type":"user","message":{"role":"user","content":"..."},"msgV":1}

Optional fields on that message: priority (now / next / later, default next),
msg_id, from, session_id — a session_id that does not match the target
session causes the message to be dropped. Line length is capped at 1 MiB and the
first complete line must arrive within 30 s.

Authentication is a first line, {"type":"auth","token":"<32 hex>"}. It is
optional on POSIX, where the peer is identified by SO_PEERCRED, and
mandatory on Windows, where the token is the only identity. The token lives
in ~/.claude/sessions/<pid>.<sha256 of the canonical socket path>.key, mode
0600.

There is no way to ask a session for its state. The state is read from
~/.claude/sessions/<pid>.json. Idle notification is a subscription —
{"type":"control","action":"notify_when_idle",...} — and it requires the
sender to expose an inbox of its own, at an address inside the server's
namespace, with its own key published. That is a much larger commitment than
sending.

The reference implementation is the CLI's own message-sending tool.

Measured, against a live session

A throwaway session was created on the declared host, its descriptor read, and a
single NDJSON line written to its socket with nc -U — no auth line. The
session received the prompt, answered it, and returned to idle; its
statusUpdatedAt moved to 23 s old. Round trip under 20 s.

What this decides

The messaging socket wins over a trigger file, for a POSIX host:

• it needs nothing installed on the host — no watcher, no relay, no hook;
• it is independent of any multiplexer and of any PTY, so it works whether or not
  the session runs under tmux, and whether or not we launched it;
• the transport is one ordinary ssh connection: ssh <host> nc -U <socket> needs
  no Unix-socket forwarding, which was the doubtful part on the Windows client.

The trigger-file route stays as the fallback for a host that has a watcher and
no reachable socket.

What is left to decide

Sending only, or sending and hearing back. Sending is a line on a socket.
Hearing back means Switchboard publishes an inbox and a key on the host — much
more surface. Polling <pid>.json, which the refresh cycle already reads, gives
the state change for free. Recommendation: send only, read state from the
descriptor.

Windows hosts. A declared host running Windows would require the token, which
means reading a .key file — the same class of file the denylist deliberately
refuses and that the descriptor fetch deliberately excludes. No declared host is
Windows today. Do not solve it now; state the limitation and refuse the tier
rather than weaken the rule.

Rate limits. The server applies a 30-token bucket refilling at 0.5/s, and
drops identical bodies repeated within 30 s. Anything that retries must respect
that rather than discover it.