## Why
In a research -> code -> oncall chain run on 2026-09-22, Raven-Code
called
`exec(machine="conn_cpu_32c")` and got "No connection is registered", on
a home
whose `connections.json` listed seven machines. It then read
host/port/key out
of the config and ran a raw `ssh root@<ip> -p <port> -i ~/.ssh/id_rsa`,
putting
the way in into the transcript.
Two gaps:
1. **Read side.** `raven.ops.connections.store_path()` looked only
beside the
instance's own config. A sub-agent runs on a rendered config in its own
state
directory, so it looked in an empty directory. The host already hands
every
sub-agent `RAVEN_HOME`; the registry just was not looked for there. Only
the
on-call launcher worked around this (it sets `RAVEN_CONNECTIONS`
itself).
2. **Write side.** `ops_connection_add` (#545) lived in the on-call
plugin. In the
usual chain the coding agent runs first, meets the empty registry first,
and
had no way to take the owner's answer.
## What changes
- `store_path()`: env var -> `raven_home()/connections.json` if it
exists ->
beside the config if THAT exists -> the home (where a first add lands).
An
install that kept its own list beside its config keeps working.
- New `raven/ops/connection_add.py`: `probe`, `ssh_defaults`,
`parse_probe`,
`write`, `write_ssh_alias`, and `ASK_OWNER` (the questions relayed to
the owner).
The tool calls these functions directly; `raven ops connection add` (the
terminal command for a person) calls the same ones, so the logic exists
once.
- New `raven/agent/tools/connection_add.py`: `ops_connection_add` as a
trunk tool,
**opt-in** via `tools.connectionAdd` (on in raven-code and raven-oncall,
off in
the other three products, whose pinned tool faces are unchanged).
- `raven.ops.transport.make_ssh_runner(identities_only=)` +
`ISOLATE_IDENTITY`,
moved from the plugin: a key the tool picked itself is probed with that
key
alone (see #545 review).
- On-call plugin: `oncall_flow/connections.py` imports trunk's reader
instead of
keeping a hand-aligned copy (758 -> 212 lines); keeps only campaign
lookups
(`get`, `display_name`, `resolve_into`, `describe`). Its own tool file,
factory and manifest row are removed.
- Raven-Code guide (`TOOLS_CODE.md`) gains when to leave this computer:
write
here; verify where the software is; ask the owner for a machine only
when
installing the software here is wrong (GPU, memory) or heavy (compiled
solver,
toolchain, long download); never ssh from an address in the task
statement.
- `SHOWN` made public in `raven.ops.connections` (the plugin may not
import an
underscored trunk name; `_SHOWN` stays as an alias).
- Docs: `docs-site/docs/oncall.md` / `oncall.zh.md` updated for the new
lookup
and the tool.
## Not in scope
- The pre-dispatch registry gate removed in a44664d1b is NOT restored.
Where a
job runs is still decided inside the agent that runs it; this only makes
that
agent find the owner's registry and able to add to it.
- #552 (exec refuses a typed ssh to a registered machine) is
complementary: it
only fires once the registry is visible, which this makes true for
Raven-Code.
## Tests
- `tests/test_ops_connection_add.py` (moved from the plugin suite,
patches trunk
modules), including the ssh `-G` measurement that only the candidate key
is
offered under isolation.
- Five new cases in `tests/test_ops_connections.py` for the lookup
order.
- Plugin parity tests replaced by an identity pin (the plugin's names
ARE trunk's
objects).
- Code launcher face ledger gains a machine lane; oncall face unchanged.
- Full suite: see CI.
@LivXue -- review requested: this touches `raven/ops` and the
`RAVEN_CONNECTIONS`
handoff described in a44664d1b.
Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
Generated with Claude Code (https://claude.com/claude-code)
---------
Co-authored-by: xiaotian.luo <xiaotian.luo@thetahealth.ai>
Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>