## Summary
First of a series of changes that let an ACP sub-agent run on a machine
in the
machine registry (`connections.json`), reached over ssh, so one turn can
dispatch work to agents on several machines at once.
The approach was measured first, on two registered Linux machines and
without changing code: raven's own `AcpClient`, started on an `ssh`
line,
already drives a remote `claude-agent-acp` and `qwen --acp` (handshake,
`session/new`, `session/cancel`, 10 connections at once), and a remote
agent exits once the local ssh is killed -- idle within 15 s, and mid
tool call within 2 s, its child command included. What breaks is
everything that assumes the agent shares this disk; the first of those
is that an agent refuses a `cwd` that does not exist where it runs
(`-32602 cwd does not exist on the machine running the agent`).
This change adds the pieces only a remote agent needs, with nothing
calling them yet:
- `raven/acp_client/remote.py`
- `machine(id)`: the registered ssh machine. Refuses an unknown id, an
unreadable registry, an entry with a blocking problem, and a local
row, each in one sentence. Looked up in the caller, the way the
machine channel looks one up, since main keeps the registry's
readers to what its callers need.
- `launch_command()`: the ssh line, as the one string the pool and
`AcpClient` already take as a command (`shlex.join`, so their
`shlex.split` gives back the argv). Built from the registry at
launch and never stored, so no address, port or key path reaches a
config file, log line or model. The agent starts in the machine
user's login shell (`$SHELL -lic`): measured, agents installed
through nvm or into `~/.local/bin` are on that PATH and no other.
The remote command is one argv element after `--`, quoted once per
shell that reads it -- the hand-written form
`ssh host -- bash -lic 'qwen --acp'` loses `--acp` to the far
shell's re-parse and hangs to the initialize timeout.
- `ssh_log_path()` / `read_ssh_log()`: ssh's own messages name the
address ("connect to host <ip> port <n>", and on a first connect
"Permanently added '[<ip>]:<n>'"). The launch line sends them to an
owner-only log per agent (`ssh -E`) instead of to stderr, which the
connection journals and quotes in its errors; they are read back
only to classify a failure. Measured: with `-E`, stderr carries the
far side's output and nothing of ssh's.
- `session_dir()`: `<root>/<handle>` made on the machine and resolved
to an absolute path in one round trip (0.17 s measured). A directory
the machine will not make is reported with the machine's own last
word -- measured on a registered machine whose disk had filled, "No
space left on device" -- skipping any line that carries the address.
- `explain()`: one sentence for an ssh-level failure (timed out,
unreachable, login refused, host key changed, agent not installed),
naming the machine and never its address.
- `raven/ops/transport.py`: the ssh options move into `ssh_argv()` and
the row's address into `ssh_target()`, so the one-shot runner and a
remote agent share one spelling. The runner sends the same argv as
before; a new test pins it.
- `docs/specs/2026-08-11-acp-local-agent-mesh-design.md`: its "remote
agents" non-goal carries a dated amendment pointing at `remote.py`.
ACP still runs over stdio only; the local process is ssh.
The next change (#897) wires this into the ACP backend behind a
`machine`
field on an agent's entry. Later changes add a small Raven process on
each registered machine that
reads and writes files there for this one, so the main agent can read a
remote file's lines without copying the file; scp-style remote paths for
the file tools; and `machine` on `subagents.add`.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `uv run pytest tests/test_acp_remote.py tests/test_ops_transport.py
tests/test_ops_connection_add.py tests/test_shell_machine_channel.py
tests/test_ops_connections.py`
-- all passed. The quoting cases run the remote command through real
shells here (`sh -c` standing in for sshd, `$SHELL -lic` for the login
shell, `HOME` in a temp dir): the agent's own arguments arrive intact,
a variable valued ``a b 'c' "d" $HOME `id` \e`` arrives unexpanded,
a `~` root with a space in it is made and entered, a relative root
comes back absolute from the login's home, and an agent on the PATH
only a login shell's `.profile` sets is found.
- The same generated command run under dash on a registered Linux
machine: same argv, cwd and value.
- Real machines, through `remote.py` and raven's `AcpClient`, against a
scratch registry (not `~/.raven`): the session directory was made and
resolved on the machine, `claude-agent-acp` answered `initialize` and
accepted `session/new` in that directory; a machine that does not
answer, an unregistered id, a wrong key and an agent that is not
installed each came back as one sentence with no address in it. The
remote test directory was removed afterwards and no process was left.
- `uv run pytest --ignore=tests/integration --idle-ceiling-strict` --
27800 passed, 119 skipped, 3 failed:
`test_rpc_files.py::test_a_host_without_libreoffice_says_so`,
`test_simulation_scenario.py::test_a_fresh_trial_refreshes_the_subagent_homes_before_it_runs`
and
`test_simulation_suite.py::test_a_stopped_run_is_marked_in_its_record_and_finished_with_its_evidence`,
which fail the same way on main on this machine.
- Diff coverage over the changed lines: 99% (the gate asks for 90).
- Twenty mutations, each reverting one part of the change, each
turning a test red: the machine's reason dropped, the line carrying
the address kept, the inner command not quoted for the outer shell,
the variable assignments not quoted, `-T` dropped, `--` dropped, the
extra options placed after the destination, the runner's host-key
option dropped, ssh's own words passed on, the host-key failure not
recognised, an unsafe handle kept without its digest, a slash allowed
in a handle, a local row accepted as a remote machine, an entry with a
blocking problem accepted, the session directory echoed instead of
resolved on the machine, a failed `mkdir` taken as success, a `~` root
quoted so the shell cannot expand it, the agent not started in the
root, a bad variable name let through, and the agent started outside
the login shell
- `scripts/check_source_language.py`, `scripts/check_commit_messages.py`
and `scripts/check_large_files.py` on the branch range, and the
prospective squash header and the commit through `commitlint` -- all
clean
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
Nothing user-facing changes yet: no entry can name a machine until the
next change.
## Risk
No behaviour change. `remote.py` has no caller yet, and the one-shot
ssh runner sends the same command line as before, pinned by a test. The
launch line carries the machine's address, which is why it is built at
launch and held only in memory; variables travel on that line too, so
the design keeps secrets off it (no lent keys for a remote agent).
Rollback is a plain revert.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>