feat(mesh): AckermannRosRobot - Ackermann ROS 2 cars (AWS DeepRacer) as strands robots - #2689

Ackermann ROS 2 cars (AWS DeepRacer) as strands robots, brought current with main

Continues @Vivek0712's #1035, whose commits are ancestors of this branch. That
PR is a complete, reviewed feature that has been unmergeable on a textual
conflict since 2026-08-04. This branch carries it forward: main merged in,
the conflict resolved, and the two defects that its stale base was hiding
fixed.

The feature

RosBridgedRobot covers differential-drive bases (a Twist on cmd_vel plus
odometry). An Ackermann car exposes neither. AckermannRosRobot keeps the same
drive(linear, angular, duration) agent contract and converts through a
bicycle model to normalized servo commands (ServoCtrlMsg on the DeepRacer),
runs a declarative init_services handshake once before the first command,
clamps speed, refuses over-long holds loudly, and always trails a timed command
with a zero servo message so a timed drive cannot leave the car driving. It
validates through the same finite_number_error,
positive_finite_number_error and positive_whole_number_error domains the
three differential-drive bridges call, so the fourth transport refuses an
unusable velocity, hold or count with byte-identical text.

The conflict

One file, docs/ros2-integration.md, where both sides appended a new section at
the same anchor: this branch a new ## "Ackermann robots (AWS DeepRacer)"
section, main a ### "Safety-critical command surfaces need operator
approval" subsection. Both are kept. main's block goes first because it is an
h3 that continues the pre-existing ## Safety section - putting the new h2
first would nest main's subsection under "Ackermann robots". Resulting order
is ## Safety -> ### Safety-critical ... -> ## Ackermann robots ... ->
## Sim bridge ....

Two defects the stale base hid

The branch's checks were green, and correctly so - both guards that fail it
landed on main after its base (c1acf21d), and neither guard's file is one
the branch touches, so there is no file overlap to notice:

1. __repr__ on a half-built instance. __init__ validates node_name
through _check_topic before assigning it, so a refused construction leaves the
instance the raising frame keeps alive rendering as

[AttributeError("'AckermannRosRobot' object has no attribute 'node_name'") raised in repr()]

which sends the reader after node_name when the real failure is the
ValueError: invalid node_name: 'bad name!' they already caused. Now wrapped in
try/except AttributeError delegating to strands_robots.utils.partial_construction_repr,
exactly as RosBridgedRobot, RosbridgeRobot and RtpsRobot do, so the phrase
a reader learns to recognise in a traceback has one owner. Half-built now renders
AckermannRosRobot(partially constructed, id=0x...). The class is triaged into
both halves of that module's survey - the half-built sweep and the
documented-refusal cases - for parity with the other three bridges.

2. drive/stop survey inventory. test_the_survey_finds_the_bridges_it_is_meant_to_cover
is the non-vacuity half of the drive/stop guard: it pins that the scan finds the
bridges it is meant to cover, so a mis-rooted or empty survey cannot read as
compliant. A fourth drive/stop bridge has to be triaged there. The rule itself
already covered the class - the survey walks the mesh package - and renaming its
stop_ tool fails test_every_bridge_owning_a_drive_stop_pair_builds_a_stop_tool.
It stays out of BRIDGES deliberately, with the reason recorded next to the
inventory: those cases assert a zero geometry_msgs/msg/Twist on /cmd_vel, and
an Ackermann car halts with a zero ServoCtrlMsg (angle/throttle) on its
servo topic, which tests/mesh/test_ackermann_robot.py already pins.

Verification

Regression split, on the merged tree, over the two guard files:

The three are the two repr cases plus the inventory case; the delta to 65 is
those three plus the two new parametrized cases the class now contributes.

Each fix is load-bearing, checked by mutation:

Zero regressions, over 296 tree-walking guard files plus all of tests/mesh,
run identically on this branch and on a pristine upstream/main worktree:

The five failing ids are identical on both trees and all environment-bound
(four DID NOT RAISE ImportError where rclpy is importable, and one
auth_mode case sensitive to a mesh env var another test in the selection
sets). The +47 passed is this branch's own suite plus the two new cases.

ruff check and ruff format --check clean over strands_robots tests tests_integ. mypy over the same scope: 19 errors on this branch and 19 on
pristine main, with the branch-only difference empty. assemble_changelog.py --check OK.

No visual artifact: the diff adds a ROS 2 transport bridge and a __repr__
fallback, and changes no simulation, rendering or policy behaviour.

Supersedes #1035. Its changelog fragment is kept and extended with the repr
fix rather than replaced.

Round 2 changes

Two review concerns, both on safety paths in the changed code, one commit each,
plus the rule the second belongs to recorded where the next bridge will read it.

1. The trailing safety stop's verdict was discarded (fcb5ed4). drive sent
its trailing zero servo message from a finally and dropped the result, so when
the main publish succeeded and the halt then failed - node or daemon dying
mid-hold - the caller saw the drive's success for a car still holding the
commanded throttle, on a tool whose description promises that a command with a
duration stops itself. The halt's result is now captured into a local from the
finally (so it still goes out when the main publish raises) and, when the drive
succeeded but the halt did not, returned as an error naming the published
command, the possibly-live throttle, stop as the next action, and the halt's
own cause. A failed drive stays the reported cause; a latching single-shot sends
no halt, so there is no verdict to read.

Three cases in tests/mesh/test_ackermann_robot.py, next to
test_drive_trailing_zero_sent_even_when_publish_errors which covers the inverse
direction: the failed-halt case, the both-failed precedence, and a control that a
single-shot success is not reinterpreted. Restoring the discard fails the first.

2. The bridge's commands were outside the use_ros operator gate (43ee3d5).
Both halves were missing. The gate only fires on a blocklisted surface, and the
shipped DeepRacer wiring matched no entry (/webserver_pkg/manual_drive, and the
/ctrl_pkg mode services that arm the vehicle), so every servo publish and
handshake call went out with no prompt, no allowlist check and no audit row -
while the functionally identical /motor_enable was blocked. And nothing here
carried an operator context, so fixing coverage alone would have made every
command, stop included, a fail-closed refusal.

Pinned by tests/mesh/test_ackermann_command_gate.py (18 cases), which keeps the
real use_ros and doubles the rclpy transport instead - the boundary
test_ackermann_robot.py patches over, which is why neither half was visible
there. It covers the prompt order over all three surfaces, a decline at the
handshake and at the servo topic, the halt reaching the operator, a timed drive's
trailing halt, both allowlist spellings, the headless refusal naming both
variables, and structural guards on context=True and on every command call
site. TestEveryCommandingMeshBridgeHasAGateSuite derives the mesh modules that
send a command through use_ros from the tree and compares them against an
inventory of gate suites, so a fifth bridge is graded on arrival rather than
shipping ungated the way this one did.

Doc drift closed in the same commits, at every surface an operator reads to size
a pre-approval: the blocklist table and the final-path-segment example list in
docs/ros2-integration.md, a per-method gated-surface table plus the
STRANDS_ROS2_COMMAND_ALLOW line in its Ackermann section, the surface
enumeration and the context-forwarding sentence in docs/security.md, the
example's SAFETY block, and the class and module docstrings. The changelog
fragment carries both fixes.

3. The rule, recorded (d44be59). AGENTS.md convention 18: a new bridge
ships un-gated because the gate is keyed on surface names it does not know, and a
bridge suite that patches the module's use_ros symbol cannot see it - so naming
the surfaces and threading the context are one change, either alone being a
different defect. It names the pin above rather than restating the rule, since
that pin's inventory is derived from the tree.

Round 2 verification. Same selection on this branch and on a pristine
main worktree (tests/mesh, tests/tools/test_use_ros.py,
tests/test_use_ros_command_blocklist.py,
tests/test_repr_survives_partial_construction.py,
tests/test_args_docstring_completeness.py,
tests/test_docstring_xref_roles_resolve.py):

The 136 failing/erroring ids are byte-identical between the two trees and all
bound to optional dependencies absent from this runner (90 json5, 44 awsiot,
1 lerobot, and one pre-existing test_iot_camera_ref_delivery assertion). The
+65 passed is this branch's new gate suite (18) plus its own earlier cases. The
968-test sweep of every guard that reads AGENTS.md passes (one lerobot-bound
failure, present before the edit). ruff check and ruff format --check clean
over strands_robots tests; mypy reports zero errors in either changed source
file, and its count on use_ros.py is 11 on both trees; assemble_changelog.py --check OK.

Round 3 changes

No review feedback outstanding; this round is a base merge forced by a sibling
change, plus the absorption its sequencing note called for.

main landed the ROS 2 command gate as a shared owner,
strands_robots/tools/_command_gate.py, so that use_rtps and use_rosbridge
consult the same blocklist as use_ros - a surface refused on one transport can
no longer be sent on another. Round 2 above added three DeepRacer surfaces to
that blocklist and extended the two docs/security.md sentences describing it,
while it still lived in use_ros.py. Both sides therefore edited the same text,
and this branch went CONFLICTING the moment that change merged.

The three surfaces move to _command_gate.COMMAND_BLOCKLIST unchanged, which
widens what round 2 achieved: /manual_drive, /vehicle_state and
/enable_state are now gated on all three transports rather than only on
in-process rclpy. Their justification moves with them, minus the
bare-entry/final-segment rule the shared comment already states. The two
docs/security.md sentences regain the Ackermann servo topic and arming
services in the enumeration, and AckermannRosRobot beside RosBridgedRobot as
a context forwarder. docs/ros2-integration.md merged with no conflict and
carries both the transport axis and this branch's surface table.

Three symbols this branch referenced moved with the gate, so its own suite and
the rule recorded in round 2 name them at the new owner:

A tree-wide sweep confirms no reference to any of the old names survives, in
source, tests or AGENTS.md.

Round 3 verification. The 12 suites covering the gate, the Ackermann bridge
and both sibling transports: 545 passed, 1 skipped. The whole-tree graders
that read the edited docs and AGENTS.md: 111 passed.

Full tests/ on the composition and on a pristine main worktree, same
interpreter and same environment:

Read as a delta, per the rule that an absolute count in a partial environment
invents regressions: the failing-and-erroring id sets are compared directly and
the branch-only set is empty, with identical 627/981 totals on both trees.
Every one is an absent optional dependency here (torch, mujoco, lerobot,
rclpy, device_connect_edge, json5, awsiot). The +68 passed is this
branch's own tests.

ruff check and ruff format --check clean over strands_robots tests
(1469 files already formatted).