feat(examples): add cross-zone robot transport

[haofeif]

Summary

Refs #845. Implements Transport across ownership zones as the first simulation-only robotics example, rather than adding a robotics framework to CAO or claiming the entire example catalogue is complete.

• Existing CAO CLI agents own planning, robot selection, delegation, zone operations, and independent checking. A real Copilot CLI supervisor delegates through CAO handoff; zone workers and the checker use a shared, authenticated MCP simulator.
• One persistent MuJoCo world outlives short-lived workers. Measured dock arrival, explicit offers, and receiving-side acceptance govern custody. Command history distinguishes accepted, running, finished, rejected, failed, interrupted, and unknown outcomes without blind replay.
• Read-only credentials cannot acquire movement rights through tool arguments or prompts. Zone identity comes from authentication. Operator approval, bounded execution, and an independent stop remain below model reasoning.
• Robotics dependencies are isolated in the example's own project and lockfile. Shared prompts and scene data support different zone/robot configurations without natural-language routing rules or fixture-specific execution branches.
• Includes setup, observation, stopping, cleanup, limitations, regression coverage, and a dedicated Python 3.10/3.12 simulator workflow. prepare --request requires an explicit nonblank goal and emits a complete, safely quoted nonblocking launch command. No new provider, driver, workflow engine, or normal-install dependency.
• Closes the review-reported workflow-delegation permission gap through the existing shared MCP guard. All six delegation entry points require the caller's @cao-mcp-server or * grant. Unbound operators remain unrestricted; ephemeral callers still need their separate opt-in. This is the only core behavior change, and no robotics logic enters CAO core.

Real CAO acceptance

These were actual authenticated Copilot CLI agents using the real headless MuJoCo controller and HTTP/stdio MCP connections, not a scripted replacement planner. Each case used a fresh world, credentials, profiles, and CAO session. They ran on the initial example before the shared authorization correction; the simulator implementation is unchanged, and the follow-up permission regressions cover the corrected delegation boundary.

Case	Contributing CLI agents	Measured result
Default cross-zone delivery	Supervisor, west operator, east operator, independent checker	Run 9477448dfd574391b0ec4d6cab60e129: tote at [2.0, 0.0] m, location etch, owner east, no pending offer. Both moves, the custody offer, and the exact receiving acceptance finished. Checker observation: 2026-10-06T08:18:41.304413Z.
Unavailable destination	Supervisor and independent checker	Run eb8cfec34492446b908472f6f8b76046: cleanroom explicitly unavailable; no substitution, motion, or custody command. Tote remained at stock, [-2.0, 0.0] m, owned by west. Checker observation: 2026-10-06T08:57:30.095348Z.
Operator interruption	Supervisor, west operator, independent checker	Run ed905b8be44a45cd9adaeca7d684ee13: independently stopped an actual running command. Tote stayed at [-1.976, 0.0] m, between locations, still west-owned; command recorded interrupted / operator_stop. No east leg, custody offer, or replay. Checker observation: 2026-10-06T09:00:24.087757Z.
Different robot setup and request	Supervisor, stores operator, assembly operator, independent checker	Run 14eb37ae876c42758420786d7e9cae3f: returned sample-tray from rack through transfer to inspection, using different coordinates, fixtures, capacities, speeds, and names. Final pose [1.0, -0.996] m is 0.004 m from the target, within the 0.010 m tolerance; owner assembly, no pending offer, all four commands finished. Checker observation: 2026-10-06T09:01:11.848888Z.

The alternative run exceeded the synchronous launch client's 300-second wait, but its existing agents and controller continued and completed; the result was reconciled without replay. Generated and documented launch commands therefore use CAO's existing --async mode and explicitly distinguish message delivery from task completion.

All four owned CAO sessions, five listeners, sixteen generated global provider profiles, and five private run/state directories were removed after confirmed stopping. No credentials, raw account banners, or robot assets are included in the PR.

Validation

• Optional simulator/MCP/setup suite: 56 passed, using real MuJoCo and authenticated loopback HTTP MCP, including authorization, custody, capacity boundaries, stale poses, duplicate/concurrent operations, disconnects, timeout, stopping, concurrent snapshots, profile schemas, alternative scenes, and required request/message round trips.
• Three actual generated commands also round-tripped through the real CAO CLI parser with their complete message intact, including distinct goals, quotes, newlines, and option-like text; no sessions were started by this parser check.
• Delegation/workflow regressions: 305 passed, covering every dispatch route, Copilot and Claude restricted callers, selector/wildcard/profile resolution, failed authorization lookups, installed/unbound callers, and ephemeral opt-in without allowlist bypass.
• Merged-base documentation, packaging, example-profile, and dependency-inventory contracts: 265 passed, 13 skips.
• Black, isort, targeted mypy, Markdown links, and staged diff checks passed.
• Affected core-module mypy comparison against current main: 15 pre-existing errors on both base and head, zero new errors. The unchanged repository-wide mypy policy remains non-blocking.
• The locally applicable optional dependency graph was audited: 77 dependencies, zero known vulnerabilities. A separate OSV batch covered all 92 locked registry package/version entries, including conditional branches, with zero findings. Added direct dependencies' licenses were verified as Apache-2.0, BSD-3-Clause, or MIT.
• The unmodified pre-push gate passed on the latest head in an ordinary isolated checkout: 14,074 passed, 49 skipped, 117 deselected, 1 xfailed, clean JIT scan over all four rebuilt MCP App bundles, and all four bundle budgets met.
• Pushed head: 72ccbd5af9881b1c77a6c19a9fdd80e1eadfa65c, including permission fix aad3b827afe76544b9bebf13bbf33c15b2904151, launch-message fix dbc9d60bf1ba72fafb3d65e418640611c5b48eaa, and current main at 14a6d8fb9e4c0fe95ddc8051daf2f8ad571c254f. The final CI run completed successfully at 2026-10-06T12:34:30Z: 21/21 jobs passed. All 28 reported PR checks passed, including both security gates, both transport simulator jobs, Secret Scan, and cargo-deny. All five associated workflow runs, including Copilot review, completed successfully on this exact head.

Dependency blocker remediation: the initial Security Scan reported eight findings in the unchanged Docusaurus lockfile. After the maintainer merged #884, this branch incorporated that main commit rather than duplicating its dependency fixes. The latest hosted dependency gate scanned 13 locked graphs / 2,221 package entries, including the new transport lockfile and development/unfixed dependencies, with zero findings at 2026-10-06T12:18:42Z. All three clean-install mitigation suites also pass. No scan exemptions or weakened gates were added.

The PR's delta against current main remains the transport example, its supporting CI/documentation, and the narrowly coupled delegation-permission correction.

Final review

The final Copilot review reports nil findings on 72ccbd5af9881b1c77a6c19a9fdd80e1eadfa65c. All three review threads have published fixes and replies and are resolved.

Final verification at 2026-10-06T12:37:40Z rechecked every paginated conversation, review, inline-comment, and thread surface: zero unresolved actionable threads, no late findings, unchanged head/base SHAs, and all checks successful. Copilot's recommendation is not a maintainer approval: GitHub still reports REVIEW_REQUIRED. The PR remains open and unmerged.

Deliberate limits

This is an assisted kinematic simulation: cart proxies follow straight segments and directly carry the payload. It does not model wheel dynamics, grasping, collisions, obstacle avoidance, physical docking, or real-world safety. There is no hardware driver, hardware endpoint, extra Strands/LangGraph agent, or hidden reasoning loop.

The local account and private run directory are trusted; scoped MCP credentials and provider-native tool restrictions are not an OS sandbox or production multi-tenant authorization system. Initial robots must already be positioned for pickup and receiving. Restarting a consumed run is refused; recovery requires inspection and a fresh prepared run rather than silently resetting command history.

[Copilot]

Copilot review overview

🟡 Changes recommended

Restricted Copilot profiles can still access workflow-based CAO delegation through the automatically injected MCP server.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Restrict CAO workflow tools for non-delegating Copilot profiles · New
• Prevent generated Copilot profiles from invoking workflow orchestration · New

What changed in this PR

Adds an isolated, simulation-only cross-zone robotics example using CAO agents, authenticated MCP tools, and a persistent MuJoCo world.

Changes:

• Implements bounded transport, custody handoffs, stopping, and scoped access.
• Adds scenarios, prompts, tests, dependencies, and dedicated CI.
• Documents operation, limitations, cleanup, and contributor checks.

File	Description
.github/​workflows/​ci.yml	Formats the robotics example.
.github/​workflows/​robotics-transport.yml	Tests Python 3.10 and 3.12.
CHANGELOG.md	Records the new example.
README.md	Links the robotics example.
skills/​cao-contributing/​SKILL.md	Documents the new CI check.
src/​cli_agent_orchestrator/​skills/​cao-contributing/​SKILL.md	Updates packaged contributor guidance.
examples/​robotics/​cross-zone-transport/​README.md	Documents setup, operation, and limitations.
examples/​robotics/​cross-zone-transport/​demo.py	Generates profiles and manages controller access.
examples/​robotics/​cross-zone-transport/​pyproject.toml	Defines isolated dependencies.
examples/​robotics/​cross-zone-transport/​uv.lock	Locks the example dependency graph.
examples/​robotics/​cross-zone-transport/​simulation.py	Implements the shared MuJoCo world.
examples/​robotics/​cross-zone-transport/​transport_mcp.py	Exposes authenticated MCP tools.
examples/​robotics/​cross-zone-transport/​site.json	Defines the default scene.
examples/​robotics/​cross-zone-transport/​return-site.json	Defines the alternative scene.
examples/​robotics/​cross-zone-transport/​prompts/​supervisor.md	Guides transport coordination.
examples/​robotics/​cross-zone-transport/​prompts/​zone.md	Guides zone operations.
examples/​robotics/​cross-zone-transport/​prompts/​checker.md	Guides independent verification.
examples/​robotics/​cross-zone-transport/​tests/​test_simulation.py	Tests transport and custody behavior.
examples/​robotics/​cross-zone-transport/​tests/​test_mcp.py	Tests authentication and controller boundaries.
examples/​robotics/​cross-zone-transport/​tests/​test_setup.py	Tests generated profiles and run setup.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟡 Changes recommended

The generated launch command omits the transport request, so copying it does not execute the example.

Review effort: Balanced
Findings: 1

Open (1)

• Generated cao launch command omits required transport message · New

Resolved since last review (2)

• Restrict CAO workflow tools for non-delegating Copilot profiles
• Prevent generated Copilot profiles from invoking workflow orchestration

[Copilot]

Copilot review overview

🟢 Approval recommended

The implementation is isolated, authorization is consistently enforced, and comprehensive exact-head CI passed.

Review effort: Balanced
Findings: None

Resolved since last review (1)

• Generated cao launch command omits required transport message