refactor(*): one registry reader and one writer, and the coding agent can add a machine

[silverLXT]

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 (feat(raven-oncall): let the on-call instance add the machine the owner describes #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 feat(raven-oncall): let the on-call instance add the machine the owner describes #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 a44664d 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.
• fix(agent): exec refuses a typed ssh to a machine the registry knows #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 a44664d.

Co-authored-by: Claude (claude-opus-5-5) noreply@anthropic.com

Generated with Claude Code (https://claude.com/claude-code)

[gloryfromca]

Blocking: the shared SSH probe no longer enforces its advertised timeout.

I reviewed the full github/main...HEAD diff and relevant surrounding code, callers, and history. I also checked AGENTS.md plus the Runtime/agent terminology and architecture in CONTEXT-MAP.md, CONTEXT.md, and agents/README.md; backward compatibility of registry-path resolution; the moved writer and both product launch paths; and the test changes for weakening. The home-first precedence is deliberate and covered, and the reader/writer consolidation otherwise preserves the existing contracts.

Verification:

• uv run pytest tests/test_ops_connection_add.py tests/test_ops_connections.py tests/test_cli_ops_connection_commands.py tests/test_shell_machine_channel.py tests/test_agents_oncall_flow_connections.py tests/test_agents_oncall_flow_watcher.py tests/test_agents_oncall_launcher.py tests/test_agents_code_launcher.py -x - 195 passed.
• uv run pytest - 19,932 passed, 130 skipped, 74 failed, 283 errors; the failures/errors are outside this diff and are dominated by optional packages/plugins absent from this checkout (for example websockets, raven_everos, raven_design, and raven_ppt).
• A direct patched call to probe(..., timeout=0.25) confirmed that the remote runner invokes subprocess.run without a timeout.

Once the SSH execution deadline is restored, I see no other blocker in this revision.

[gloryfromca]

No blockers; this can merge as far as I am concerned.

I re-read the full github/main...HEAD diff and the change since ac98cb2. I checked the repository rules and Runtime/agent architecture documents, the shared transport callers and history, registry-path and CLI backward compatibility, and the changed tests for weakening. The SSH deadline now reaches the normal and isolated-key probe paths, returns the transport's existing rc 124 on timeout, and is rendered as a no-write refusal. I found no new issue in the revision.

Verification: uv run pytest tests/test_ops_connection_add.py tests/test_ops_connections.py tests/test_cli_ops_connection_commands.py tests/test_shell_machine_channel.py tests/test_agents_oncall_flow_connections.py tests/test_agents_oncall_flow_watcher.py tests/test_agents_oncall_launcher.py tests/test_agents_code_launcher.py -x - 213 passed. I also replied to and resolved my prior timeout thread.

[gloryfromca]

No blockers; this can merge as far as I am concerned.

This revision merges current main; after refreshing github/main, the PR remains the same 28-file registry change. git range-diff shows both authored commits are unchanged from the revision I previously reviewed. I rechecked the full PR diff, repository rules and Runtime/agent architecture constraints, callers and history, backward compatibility, and the tests for weakening, with particular attention to the newer machine-exec guard now on the base. I found no new issue, and my earlier timeout thread remains resolved.

Verification: git diff --check github/main...HEAD passed; uv run pytest tests/test_ops_connection_add.py tests/test_ops_connections.py tests/test_cli_ops_connection_commands.py tests/test_shell_machine_channel.py tests/test_agents_oncall_flow_connections.py tests/test_agents_oncall_flow_watcher.py tests/test_agents_oncall_launcher.py tests/test_agents_code_launcher.py -x - 283 passed.

[LivXue]

Blocking: 1 finding(s) need correction before this revision can merge; see the inline notes.

Scope: I reviewed only the raven/agent/** portion of this PR -- 5 of 28 changed files: the new raven/agent/tools/connection_add.py and its wiring in raven/agent/loop/. The remaining 23 files were read as context but are not covered by this verdict. raven/agent/subagent/ is untouched, and the new registration does not reach spawn or run_subagent_dag: built-in sub-agents assemble their own registry (raven/agent/subagent/backends/raven_loop.py) and are never handed the flag, and both products that turn it on disable both dispatch tools.

What I examined: the new tool against its plugin predecessor (the execution path is unchanged; the model-facing description and success reply now also name exec's machine parameter); every non-test construction of ToolWiring and every caller of build_runtime (the flag reaches acp, the gateway including its rebuild, agent and a2a; replay replaces the registry wholesale); the plugin's _wired gate and face roster that the move retires; the permission tier and tool-search visibility, both keyed by tool name and so unchanged; and the import contracts.

Confirmed findings:

• Blocker, inline at raven/agent/tools/connection_add.py:207: when the registry is empty at process start, exec's schema is frozen without machine, yet after the first add this reply, the fix(agent): exec refuses a typed ssh to a machine the registry knows #552 refusal and the Raven-Code guide all send the model to exec(machine=...). Reproduced.
• Nonblocking, inline at raven/agent/loop/wiring.py:944: the tool has no group in the settings table, and the guard for that builds a loop that cannot register it. Reproduced.

Outside the reviewed scope, disclosed here because no inline note can be filed there:

• Question, raven/ops/connections.py:314-321. Home-first is right for a sub-agent, where the file beside a rendered config is a stale copy, but not obviously for a host started with --config /x/config.json, where the file beside the config is the owner's own list: once any registry appears in raven_home(), that host switches to it. One probe, run at both revisions (a --config host with conn_cpu_32c in /x/connections.json, then a first home registry appears): at the merge base the host reads /x/connections.json before and after; at 257acb1 it reads it before, and afterwards only the home file (['conn_new']). A coding agent's first add for an owner with no registry writes exactly that home file, so the switch no longer needs the owner to run anything. The same shape reaches connections_registry() in agents/raven-oncall/run.py:112-126: an install that kept its own list and has no home file drops that list at the next launch after a coding-agent add (reproduced: both rows still on disk, unread). Separately, the product children of a --config host see its registry neither before nor after this PR, since their launchers render a config of their own and inherit only RAVEN_HOME. docs-site/docs/oncall.md does say a registry beside a config elsewhere is read "when the home has none", so the precedence is documented; the question is whether it is meant to cover a --config host.
• Nonblocking, CONTEXT.md:339-349. The canonical Machine entry still says rows are registered with raven ops connection add, held "beside the config or wherever RAVEN_CONNECTIONS points", and handed over by the launcher's pointer. After this PR an agent tool writes rows, the store resolves home-first, and, in this PR's own commit message, the launcher's pointer "is no longer the only thing that does". Code-reading.
• Nonblocking, agents/raven-oncall/plugins/oncall-flow/oncall_flow/connections.py:205-213. _PROBE has no reader left in the tree, and "Mirrors the CLI's probe line" no longer holds: the probe line is raven.ops.connection_add.PROBE_SCRIPT now. Code-reading (a tree-wide grep finds no other reference).

Verification, all at 257acb1 against an extracted head tree, with the imported raven confirmed to come from that tree:

• lint-imports: 10 contracts kept, 0 broken.
• pytest tests/test_ops_connection_add.py tests/test_ops_connections.py tests/test_cli_ops_connection_commands.py tests/test_shell_machine_channel.py tests/test_agents_oncall_flow_connections.py tests/test_agents_oncall_flow_watcher.py tests/test_agents_oncall_launcher.py tests/test_agents_code_launcher.py tests/test_tool_capabilities.py tests/test_settings_tool_groups.py tests/test_agent_loop_tool_search.py: 339 passed, 1 failed. The failure, test_shell_machine_channel.py::test_the_table_agrees_with_the_ssh_on_this_computer[tag-value], fails the same way at the merge base on this machine (OpenSSH 8.9p1), so it is local and not this PR's.
• The two inline findings and the --config A/B were reproduced with the probes described above and in the notes.

Checked and not reported: the plugin's face roster serves only tools with set_context or a scheduler, so retiring adopt for this tool loses nothing; the _wired gate and tools.connectionAdd coincide in the shipped on-call config; trunk's _BUDGET_UNITS matches the plugin's former tuple exactly; the moved connection-add suite grew from 6 cases to 27 with none lost (one renamed). gloryfromca's SSH deadline finding from the earlier round is resolved at this head and is not re-filed. In passing: every ssh runner, trunk's and the plugin's former one alike, inherits the caller's stdin, which under raven acp is the protocol stream. That is identical at the merge base, code-reading only, and not attributable to this PR.

[LivXue]

Requesting changes for the blocking finding at raven/agent/tools/connection_add.py:207. The scoped summary and the other notes are in the comments above.

[gloryfromca]

Blocking: exec's model-facing schema must gain the machine parameter after the first registry write.

The new review evidence changes my prior clean stance on this revision. I reproduced the first-add transition against ToolRegistry: ExecTool.parameters becomes machine-aware after a row is added, but the registry continues serving the frozen schema admitted at startup, so the provider is not offered the parameter that ops_connection_add tells it to use. Direct dispatch accepts the undeclared argument, but that does not make it a dependable model-facing lane.

The separate settings-table note also holds but remains nonblocking: the coverage guard builds with connection_add=False, and the opt-in tool is absent from toolGroups.json.

Verification: uv run pytest tests/test_ops_connection_add.py tests/test_shell_machine_channel.py tests/test_settings_tool_groups.py tests/test_tool_registry_execute.py -x - 151 passed. A direct before/after registry reproduction showed live_has_machine=True while both the admitted and subsequently rendered definitions remained False. I replied with the measured facts on both new threads; they were opened by another reviewer, so I did not resolve them.

[gloryfromca]

No blockers; this can merge as far as I am concerned.

Reviewed the new revision and the full PR against the repository rules and Machine architecture. The previous schema blocker is fixed: ExecTool now explicitly declares a dynamic schema, so ToolRegistry.get_definitions() reflects the first real registry write on the next model call. The settings-table follow-up is also addressed by grouping ops_connection_add and enabling the opt-in tool in the coverage guard.

I also checked the added registry-path compatibility correction against its callers and history: an existing config-adjacent registry remains authoritative, while rendered configs without their own registry still fall back to the owner's home. The tests exercise both sides. I found no weakened coverage or backward-compatibility regression in the delta.

Verification: uv run pytest tests/test_ops_connection_add.py tests/test_ops_connections.py tests/test_cli_ops_connection_commands.py tests/test_shell_machine_channel.py tests/test_settings_tool_groups.py tests/test_agents_oncall_flow_connections.py tests/test_agents_oncall_flow_watcher.py tests/test_agents_oncall_launcher.py tests/test_agents_code_launcher.py tests/test_tool_registry_execute.py -x (314 passed). I covered the project rules and domain terminology, the full diff and new delta, relevant callers and history, backward compatibility, test changes, and the one-reader/one-writer architecture.

[silverLXT]

Addressing the review summary (a525fcf, 5146f0a). Both inline findings are fixed and replied to; the out-of-scope notes:

• --config question -- you were right, it is not meant to cover that host. The order is now: RAVEN_CONNECTIONS, else connections.json beside the active config when one is there, else the raven home (where a first add lands). A --config /x/config.json host keeps reading /x/connections.json after a home registry appears; a sub-agent still resolves the home, since nothing is ever written beside its rendered config. connections_registry() in agents/raven-oncall/run.py takes the same order, so an install that kept its own list no longer drops it after a coding-agent add. Pinned by test_a_list_beside_the_config_keeps_winning_after_a_home_registry_appears and test_an_own_registry_stays_after_a_home_registry_appears; the old home-wins test is replaced. CHANGELOG and both oncall doc pages say the new order.
• CONTEXT.md Machine entry -- rewritten: registered by the CLI or by ops_connection_add, and the lookup order above.
• _PROBE in the on-call plugin -- removed; nothing read it.
• test_the_table_agrees_with_the_ssh_on_this_computer[tag-value] on OpenSSH 8.9 -- that was fix(agent): exec refuses a typed ssh to a machine the registry knows #552's test and a real bug in it: the skip looked for the string "tag" in ssh -G output, which an older client prints as the hostname, so it never skipped. It now asks the client directly whether -P tag host.invalid resolves to host.invalid; on 9.9 the row runs, on 8.9 it skips.

Locally: the connection, launcher, tool-face and settings suites pass (365), the settings UI suite passes (183), and the full Python suite has one failure, test_rpc_files.py::test_a_host_without_libreoffice_says_so, which fails the same way on main here.

[gloryfromca]

No blockers; this can merge as far as I am concerned.

Reviewed the revision delta and rechecked it against the full PR, prior findings, repository rules, relevant callers/history, backward compatibility, test integrity, and the one-reader/one-writer architecture. The added blank line is formatter-only, and raising the settings skeleton count from 22 to 23 matches the newly grouped ops_connection_add row; the rendered test passes rather than merely accepting a changed fixture. No prior fix is disturbed.

Verification: uv run pytest tests/test_ops_connections.py tests/test_settings_tool_groups.py tests/test_shell_machine_channel.py -x (124 passed); npm test -- src/features/settings/Skeletons.test.tsx (11 passed).

[LivXue]

No blockers in the reviewed scope.

This supersedes my summary at 257acb1, which opened Blocking: for the exec schema finding; that finding is fixed. I am leaving my change request in place while the question below is open for the author.

Scope: I reviewed only the raven/agent/** portion of this PR -- 7 of 35 changed files, now including raven/agent/tools/shell.py and raven/agent/tools/machine_exec.py from the fix. The remaining 28 files were read as context but are not covered by this verdict. raven/agent/subagent/ is untouched. ExecTool.to_schema also reaches built-in sub-agents, which construct their own ExecTool (raven/agent/subagent/backends/raven_loop.py:435), but not spawn or run_subagent_dag.

What I examined: the delta since 257acb1. 69a3dc439 merges main (ui-web commits only) and leaves this PR's own patch unchanged: the diff against its merge base, stripped of index and hunk lines, hashes the same before and after. a525fcf9a is the fix; inside the reviewed scope it authors ExecTool.to_schema and corrects the machines_registered docstring. 5146f0a43 restores a formatter blank line and the settings skeleton count. I re-ran the last round's reproductions at this head, beside 257acb1 and, where the code exists there, the merge base.

Last round, now verified at 5146f0a:

• Blocker, exec schema frozen after a first add: fixed. At the provider, over two real turns with one row written between them, the second call's exec carries machine and the machine sentence (at 257acb1, neither). The new test_the_machine_lane_appears_once_a_first_machine_is_added fails with the override removed. The author resolved the thread; I confirm it.
• Nonblocking, settings table: fixed; the guard now fails when the entry is removed. The author resolved the thread; I confirm it.
• Question, home-first under --config: both shapes I reproduced are fixed. A --config host keeps /x/connections.json after a home registry appears, and on-call keeps its own list after a coding-agent add. The fix raises the question below.
• Nonblocking, CONTEXT.md Machine entry: fixed; it states the lookup order and the tool.
• Nonblocking, orphaned _PROBE: removed.

Outside the reviewed scope, disclosed here because no inline note can be filed there:

• Question, raven/ops/connections.py:319-324 and agents/raven-oncall/run.py:125-126. Beside-the-config-first cannot tell a legacy copy beside a rendered product config from a --config host's own list, and it is wrong for the first the way home-first was wrong for the second. Two consequences, reproduced at the merge base, 257acb1 and 5146f0a:
  • (a) On-call with a legacy list of its own and no home registry: a coding-agent add lands in the home while on-call keeps reading its own list, so on-call never sees that machine (after the add it lists ['conn_cpu_32c', 'conn_gpu_2'], without conn_new). For such installs that breaks TOOLS_CODE.md:54: "the machine it writes is the one the on-call agent reads afterwards".
  • (b) A legacy copy beside the rendered config plus the owner's maintained home registry: at 5146f0a both on-call and raven-code read the copy (['conn_cpu_32c']) and lose the row added since (conn_added_since). At 257acb1 both read the home; at the merge base on-call read the home, so for on-call this is a regression.
  • The replaced test, test_the_owners_home_wins_over_a_list_beside_the_config_when_both_exist, guarded (b) ("reading it would hide every machine the owner added since"); its replacement uses the same sub-agent fixture, _rendered_config, to assert the opposite. The premise that nothing is ever written beside a rendered config holds for every writer since 041271b62 (2026-09-01), but the on-call launcher still honours a legacy list in exactly that place ("An install that predates this and keeps its own list stays on it"). Only installs still carrying a pre-2026-09-01 copy are affected. Should the rule key on whether the active config is a rendered product config, rather than on whether a file sits beside it?

Verification, at 5146f0a against an extracted head tree, with the imported raven confirmed to come from that tree:

• CI: every check passes at this head, including python lint, pre-commit diff and ui rpc contract, which failed at a525fcf.
• pytest tests/test_ops_connection_add.py tests/test_ops_connections.py tests/test_cli_ops_connection_commands.py tests/test_shell_machine_channel.py tests/test_agents_oncall_flow_connections.py tests/test_agents_oncall_flow_watcher.py tests/test_agents_oncall_launcher.py tests/test_agents_code_launcher.py tests/test_tool_capabilities.py tests/test_settings_tool_groups.py tests/test_agent_loop_tool_search.py tests/test_tool_registry_execute.py: 368 passed, 1 skipped. The skip is test_shell_machine_channel.py:757 on this machine's OpenSSH 8.9, as the commit intends; the same test failed here at 257acb1.
• Mutation checks: removing ExecTool.to_schema fails test_the_machine_lane_appears_once_a_first_machine_is_added, and removing the toolGroups.json entry fails test_tool_groups_cover_the_default_tools.
• lint-imports at a525fcf: 10 contracts kept, 0 broken; 5146f0a changes no imports.

Checked and not reported: ExecTool.to_schema re-reads the registry twice per model call (description and parameters); the array changes only when the registry goes from empty to non-empty, or becomes unreadable, so the prompt-cache prefix moves once at that point. ops_declare's connection parameter is a static free-form string, so nothing on the on-call side freezes the same way.

[silverLXT]

On the lookup question (d7c5220): yes, keyed on the process role now, as you suggested.

• A sub-agent (launched by the host with RAVEN_SUBAGENT, via subagent_role_env) reads the owner's home whenever the home holds a registry. A file beside its rendered config can only be a copy, so it is read only when the home has none -- an install older than the home registry.
• Any other instance, the --config host included, reads the list beside its config first, then the home.
• connections_registry() in the on-call launcher is home-first again, for the same reason: its state root holds only copies.

Both of your reproductions are pinned and fail with the role check removed:

• (b) test_a_sub_agent_reads_the_owners_home_over_a_stale_copy_beside_its_config -- copy [conn_cpu_32c] beside the config, home [conn_cpu_32c, conn_added_since]: the sub-agent reads the home. On-call has the twin test_the_owners_home_wins_over_an_own_copy, which replaces the one-round-old test asserting the opposite.
• (a) test_what_one_sub_agent_adds_another_reads -- two state directories, the writer's empty and the reader's holding a copy; the coding agent's add is visible to the other sub-agent.

The --config case from the previous round now runs as a host process (RAVEN_SUBAGENT unset) and still keeps /x/connections.json. raven.ops importing raven.agent.subagent.role keeps all 10 import contracts (role.py depends only on os). On this machine the six stale copies you described exist for real (hand-copied into subagent_sessions/raven-code/acp/ on 09-15..17, currently identical to their homes), which is the case (b) guards.

Locally: 658 passed across the connection, launcher, tool-face, settings, tool-search, registry and sub-agent suites; ruff check and format clean.

[gloryfromca]

No blockers; suggestions only, and they are marked inline.

The role-sensitive lookup resolves the stale-copy versus custom-config ambiguity correctly, and the writer/read-through and launcher cases are covered without weakening prior tests. I rechecked the new delta against the full reviewed PR, repository rules and Machine terminology, callers/history, backward compatibility, and the one-reader/one-writer architecture. The only remaining item is the ordinary ops-command import-cost regression marked inline; it does not prevent merging.

Verification: uv run pytest tests/test_ops_connections.py tests/test_ops_connection_add.py tests/test_agents_oncall_launcher.py tests/test_agents_code_launcher.py tests/test_subagent_host_env.py tests/test_agent_loop_subagent_role.py tests/test_shell_machine_channel.py tests/test_settings_tool_groups.py -x (262 passed).

[gloryfromca]

No blockers; this can merge as far as I am concerned.

The new delta fixes the only outstanding suggestion without changing the role-sensitive registry behavior: the role flag now lives at the lightweight raven.home boundary, while raven.agent.subagent.role preserves its public imports. A clean store_path() call no longer loads the eager sub-agent/provider graph.

I reviewed the delta against the full previously reviewed PR, repository rules and Machine terminology, relevant callers/history, backward compatibility, test integrity, and the one-reader/one-writer architecture. Verification: uv run pytest tests/test_ops_connections.py tests/test_ops_connection_add.py tests/test_agents_oncall_launcher.py tests/test_agents_code_launcher.py tests/test_subagent_host_env.py tests/test_agent_loop_subagent_role.py tests/test_shell_machine_channel.py tests/test_settings_tool_groups.py -x (262 passed).

none