rosotacom-dev 2.5.dev24__tar.gz → 2.5.dev27__tar.gz

rosotacom_dev-2.5.dev27/.github/actions/setup-just/action.yml

@@ -0,0 +1,34 @@
+name: Set up just
+description: >
+  Install a pinned just release, verified by checksum.
+
+  Nineteen jobs used to reach it with `apt-get update && apt-get install -y
+  just`, and almost all of that step's 9-15s was the index refresh — in every
+  job, including all thirteen e2e slices, where it sat on the merge gate's
+  critical path. A release tarball is ~2s.
+
+  It also stops the CI toolchain drifting: apt gave whatever noble currently
+  ships (1.21.0 at the time of writing), which changes without anything here
+  saying so.
+
+runs:
+  using: composite
+  steps:
+    - name: Install just
+      shell: bash
+      run: |
+        set -euo pipefail
+        JUST_VERSION="1.58.0"
+        CHECKSUM="4a5cc2f53e6f0f8c59092a6cc38291eb729d46a7dd95d3ae582008881b84931d"
+        URL="https://github.com/casey/just/releases/download/${JUST_VERSION}/just-${JUST_VERSION}-x86_64-unknown-linux-musl.tar.gz"
+        # Unpacked outside the checkout: a stray tarball in the working tree is
+        # a thing every later step has to not trip over.
+        workdir="$(mktemp -d)"
+        # --fail, or a transient HTTP error body is saved as the tarball and
+        # reported as a checksum mismatch, which reads like a tampered release.
+        curl -sSLf --retry 3 --retry-all-errors -o "$workdir/just.tar.gz" "$URL"
+        echo "${CHECKSUM}  $workdir/just.tar.gz" | sha256sum --check
+        tar -xzf "$workdir/just.tar.gz" -C "$workdir" just
+        sudo mv "$workdir/just" /usr/local/bin/just
+        rm -rf "$workdir"
+        just --version

{rosotacom_dev-2.5.dev24 → rosotacom_dev-2.5.dev27}/.github/workflows/benchmark-calibrate.yml

@@ -44,9 +44,7 @@ jobs:
           cache: pip
 
       - name: Install just
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y just
+        uses: ./.github/actions/setup-just
 
       - name: Set up local environment
         run: just setup
@@ -87,10 +85,15 @@ jobs:
           python-version: "3.12"
           cache: pip
 
-      - name: Install just and tmux
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y just tmux
+      - name: Install just
+        uses: ./.github/actions/setup-just
+
+      - name: Ensure tmux
+        # Preinstalled on the GitHub-hosted image, so this is a probe
+        # rather than an install — but the dependency is named, so a
+        # runner image that drops it fails here instead of inside a
+        # session.
+        run: command -v tmux >/dev/null || { sudo apt-get update && sudo apt-get install -y tmux; }
 
       - name: Set up local environment
         run: just setup
@@ -132,9 +135,7 @@ jobs:
           cache: pip
 
       - name: Install just
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y just
+        uses: ./.github/actions/setup-just
 
       - name: Set up local environment
         run: just setup

{rosotacom_dev-2.5.dev24 → rosotacom_dev-2.5.dev27}/.github/workflows/benchmark-gate.yml

@@ -50,9 +50,7 @@ jobs:
           cache: pip
 
       - name: Install just
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y just
+        uses: ./.github/actions/setup-just
 
       - name: Set up local environment
         run: just setup
@@ -87,10 +85,15 @@ jobs:
           python-version: "3.12"
           cache: pip
 
-      - name: Install just and tmux
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y just tmux
+      - name: Install just
+        uses: ./.github/actions/setup-just
+
+      - name: Ensure tmux
+        # Preinstalled on the GitHub-hosted image, so this is a probe
+        # rather than an install — but the dependency is named, so a
+        # runner image that drops it fails here instead of inside a
+        # session.
+        run: command -v tmux >/dev/null || { sudo apt-get update && sudo apt-get install -y tmux; }
 
       - name: Set up local environment
         run: just setup
@@ -142,9 +145,7 @@ jobs:
           cache: pip
 
       - name: Install just
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y just
+        uses: ./.github/actions/setup-just
 
       - name: Set up local environment
         run: just setup

{rosotacom_dev-2.5.dev24 → rosotacom_dev-2.5.dev27}/.github/workflows/dev-release.yml

@@ -71,9 +71,7 @@ jobs:
           cache: pip
 
       - name: Install just
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y just
+        uses: ./.github/actions/setup-just
 
       - name: Set up local environment
         run: just setup

{rosotacom_dev-2.5.dev24 → rosotacom_dev-2.5.dev27}/.github/workflows/image-scan.yml

@@ -33,9 +33,7 @@ jobs:
           cache: pip
 
       - name: Install just
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y just
+        uses: ./.github/actions/setup-just
 
       - name: Set up local environment
         run: just setup

{rosotacom_dev-2.5.dev24 → rosotacom_dev-2.5.dev27}/.github/workflows/nightly-e2e.yml

@@ -51,10 +51,15 @@ jobs:
           python-version: "3.12"
           cache: pip
 
-      - name: Install just and tmux
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y just tmux
+      - name: Install just
+        uses: ./.github/actions/setup-just
+
+      - name: Ensure tmux
+        # Preinstalled on the GitHub-hosted image, so this is a probe
+        # rather than an install — but the dependency is named, so a
+        # runner image that drops it fails here instead of inside a
+        # session.
+        run: command -v tmux >/dev/null || { sudo apt-get update && sudo apt-get install -y tmux; }
 
       - name: Set up local environment
         run: just setup
@@ -98,10 +103,15 @@ jobs:
           python-version: "3.12"
           cache: pip
 
-      - name: Install just and tmux
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y just tmux
+      - name: Install just
+        uses: ./.github/actions/setup-just
+
+      - name: Ensure tmux
+        # Preinstalled on the GitHub-hosted image, so this is a probe
+        # rather than an install — but the dependency is named, so a
+        # runner image that drops it fails here instead of inside a
+        # session.
+        run: command -v tmux >/dev/null || { sudo apt-get update && sudo apt-get install -y tmux; }
 
       - name: Set up local environment
         run: just setup

{rosotacom_dev-2.5.dev24 → rosotacom_dev-2.5.dev27}/.github/workflows/pr-lightweight.yml

@@ -29,9 +29,7 @@ jobs:
           cache: pip
 
       - name: Install just
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y just
+        uses: ./.github/actions/setup-just
 
       - name: Set up local environment
         run: just setup

{rosotacom_dev-2.5.dev24 → rosotacom_dev-2.5.dev27}/.github/workflows/pr-merge-gate.yml

@@ -71,9 +71,7 @@ jobs:
           cache: pip
 
       - name: Install just
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y just
+        uses: ./.github/actions/setup-just
 
       - name: Set up local environment
         run: just setup
@@ -102,9 +100,7 @@ jobs:
           cache: pip
 
       - name: Install just
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y just
+        uses: ./.github/actions/setup-just
 
       - name: Set up local environment
         run: just setup
@@ -152,9 +148,7 @@ jobs:
           cache: pip
 
       - name: Install just
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y just
+        uses: ./.github/actions/setup-just
 
       - name: Set up local environment
         run: just setup
@@ -162,35 +156,46 @@ jobs:
       - name: Validate package
         run: just package
 
-  preflight-success:
-    name: preflight-success
+  quick-gate:
+    # Everything `e2e` waits for that is not the image, and deliberately no
+    # more. It exists to answer one question — is the tree obviously broken,
+    # such that thirteen slices would burn seventy runner-minutes to say so.
+    #
+    # It replaced a `needs: preflight-success` edge that made e2e wait for the
+    # whole five-version matrix. That barrier cost 2.15 min of every gate run
+    # and had fired once in sixty runs, on `workflow-lint`, which takes 0.12
+    # min; the 2.0 min of `merge-lightweight` that set its height has never
+    # stopped an e2e round, and its expensive part is `test-nondocker-cov`
+    # (38s of 45s), which is a test suite rather than a tripwire.
+    #
+    # `lint` and `typecheck` are 4s together. The rest of this job is the fixed
+    # cost every job pays, which is also what `image` pays — so sizing the
+    # tripwire this way makes it free: e2e could not start before `image`
+    # finished anyway. Nothing merges on a weaker check than before, because
+    # `ci-success` still requires every preflight job.
+    name: quick-gate
     runs-on: ubuntu-latest
-    needs: [workflow-lint, dependency-review, build-lint, merge-lightweight, package]
-    if: always() && (github.event_name != 'pull_request' || github.event.pull_request.draft == false)
+    if: github.event_name != 'pull_request' || github.event.pull_request.draft == false
     steps:
-      - name: Check preflight jobs
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install just
+        uses: ./.github/actions/setup-just
+
+      - name: Set up local environment
+        run: just setup
+
+      - name: Is the tree obviously broken
         run: |
-          if [[ "${{ needs.workflow-lint.result }}" != "success" ]]; then
-            echo "workflow-lint failed: ${{ needs.workflow-lint.result }}"
-            exit 1
-          fi
-          if [[ "${{ github.event_name }}" == "pull_request" && "${{ needs.dependency-review.result }}" != "success" ]]; then
-            echo "dependency-review failed: ${{ needs.dependency-review.result }}"
-            exit 1
-          fi
-          if [[ "${{ needs.build-lint.result }}" != "success" ]]; then
-            echo "build-lint failed: ${{ needs.build-lint.result }}"
-            exit 1
-          fi
-          if [[ "${{ needs.merge-lightweight.result }}" != "success" ]]; then
-            echo "merge-lightweight failed: ${{ needs.merge-lightweight.result }}"
-            exit 1
-          fi
-          if [[ "${{ needs.package.result }}" != "success" ]]; then
-            echo "package failed: ${{ needs.package.result }}"
-            exit 1
-          fi
-          echo "All preflight checks passed"
+          just lint
+          just typecheck
 
   image:
     # Publish the images the e2e suite builds, once per set of build inputs,
@@ -208,8 +213,9 @@ jobs:
     # is stale" is not a state this can reach — which is the objection #226
     # raised against caching the image inline.
     #
-    # Runs beside preflight rather than after it: on a hit it inspects two
-    # manifests and stops, so it is never on the critical path.
+    # Runs beside the preflight jobs rather than after them: on a hit it
+    # inspects two manifests and stops. It is what sets when `e2e` can
+    # start, which is why `quick-gate` is sized to finish inside it.
     name: image
     runs-on: ubuntu-latest
     timeout-minutes: 60
@@ -231,9 +237,7 @@ jobs:
           cache: pip
 
       - name: Install just
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y just
+        uses: ./.github/actions/setup-just
 
       - name: Set up local environment
         run: just setup
@@ -300,8 +304,8 @@ jobs:
     name: e2e-${{ matrix.slice }}
     runs-on: ubuntu-latest
     timeout-minutes: 90
-    needs: [preflight-success, image]
-    if: always() && !cancelled() && needs.preflight-success.result == 'success' && needs.image.result == 'success'
+    needs: [quick-gate, image]
+    if: always() && !cancelled() && needs.quick-gate.result == 'success' && needs.image.result == 'success'
     permissions:
       contents: read
       packages: read
@@ -322,10 +326,15 @@ jobs:
           python-version: "3.12"
           cache: pip
 
-      - name: Install just and tmux
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y just tmux
+      - name: Install just
+        uses: ./.github/actions/setup-just
+
+      - name: Ensure tmux
+        # Preinstalled on the GitHub-hosted image, so this is a probe
+        # rather than an install — but the dependency is named, so a
+        # runner image that drops it fails here instead of inside a
+        # session.
+        run: command -v tmux >/dev/null || { sudo apt-get update && sudo apt-get install -y tmux; }
 
       - name: Set up local environment
         run: just setup
@@ -364,7 +373,7 @@ jobs:
       - build-lint
       - merge-lightweight
       - package
-      - preflight-success
+      - quick-gate
       - image
       - e2e
     if: always() && (github.event_name != 'pull_request' || github.event.pull_request.draft == false)
@@ -392,8 +401,8 @@ jobs:
             echo "package failed or was skipped: ${{ needs.package.result }}"
             exit 1
           fi
-          if [[ "${{ needs.preflight-success.result }}" != "success" ]]; then
-            echo "preflight-success failed or was skipped: ${{ needs.preflight-success.result }}"
+          if [[ "${{ needs.quick-gate.result }}" != "success" ]]; then
+            echo "quick-gate failed or was skipped: ${{ needs.quick-gate.result }}"
             exit 1
           fi
           if [[ "${{ needs.image.result }}" != "success" ]]; then

{rosotacom_dev-2.5.dev24 → rosotacom_dev-2.5.dev27}/.github/workflows/release.yml

@@ -35,9 +35,7 @@ jobs:
           cache: pip
 
       - name: Install just
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y just
+        uses: ./.github/actions/setup-just
 
       - name: Set up local environment
         run: just setup
@@ -67,9 +65,7 @@ jobs:
           cache: pip
 
       - name: Install just
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y just
+        uses: ./.github/actions/setup-just
 
       - name: Set up local environment
         run: just setup
@@ -139,10 +135,15 @@ jobs:
           python-version: "3.12"
           cache: pip
 
-      - name: Install just and tmux
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y just tmux
+      - name: Install just
+        uses: ./.github/actions/setup-just
+
+      - name: Ensure tmux
+        # Preinstalled on the GitHub-hosted image, so this is a probe
+        # rather than an install — but the dependency is named, so a
+        # runner image that drops it fails here instead of inside a
+        # session.
+        run: command -v tmux >/dev/null || { sudo apt-get update && sudo apt-get install -y tmux; }
 
       - name: Set up local environment
         run: just setup

{rosotacom_dev-2.5.dev24 → rosotacom_dev-2.5.dev27}/CONCURRENCY.md

@@ -39,6 +39,26 @@ commands *discover* the matching containers from Docker instead of recomputing
 fixed names — they clean up every instance for the requested identity/target,
 including leftovers from crashed runs.
 
+## Opting out: fixed, human-readable names
+
+A project whose machines are read by people rather than by CI — a demo or
+operations project — can set `com_container_prefix` in its `rosotacom.yaml`:
+
+```yaml
+com_container_prefix: remote-assist
+```
+
+Session communication containers are then named
+`<prefix>_com-to-<remote-peer>` (e.g. `remote-assist_com-to-center`): stable
+across runs and legible in `docker ps`, at the price of parallelism — a second
+start of the same session on the same host is a name conflict. That conflict is
+detected in the same preflight as everything else: `--force` (the session
+default) replaces the running container, `--no-force` aborts with its name.
+Conflict discovery matches **both** naming schemes, so a leftover
+instance-scoped container is still found and replaced after a project switches
+modes. Test and CI projects should leave the key unset and keep the
+collision-free instance-scoped names.
+
 ## How conflicts are detected (fail-safe preflight)
 
 Each start command checks Docker before it allocates anything, and aborts with

{rosotacom_dev-2.5.dev24 → rosotacom_dev-2.5.dev27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rosotacom-dev
-Version: 2.5.dev24
+Version: 2.5.dev27
 Summary: Host CLI for ROS OTA communication sessions.
 Author: develNor
 License-Expression: BSD-3-Clause
@@ -227,6 +227,15 @@ scripts/
 project-local directories first and shared/example directories later when one
 project should discover both.
 
+`com_container_prefix` (optional) trades concurrency for readability: when set,
+session communication containers get the stable name
+`<prefix>_com-to-<remote-peer>` (e.g. `remote-assist_com-to-center`) instead of
+the default workspace- and instance-scoped unique name. Set it in projects whose
+machines are read by people (`docker ps` during a demo, next to colleagues'
+containers); leave it unset in test/CI projects, where concurrent instances must
+never collide on a name. [CONCURRENCY.md](CONCURRENCY.md) has the exact
+conflict semantics.
+
 ### Locating packaged resources
 
 rosotacom is installed in an isolated environment (pipx, or a project venv), so

{rosotacom_dev-2.5.dev24 → rosotacom_dev-2.5.dev27}/README.md

@@ -182,6 +182,15 @@ scripts/
 project-local directories first and shared/example directories later when one
 project should discover both.
 
+`com_container_prefix` (optional) trades concurrency for readability: when set,
+session communication containers get the stable name
+`<prefix>_com-to-<remote-peer>` (e.g. `remote-assist_com-to-center`) instead of
+the default workspace- and instance-scoped unique name. Set it in projects whose
+machines are read by people (`docker ps` during a demo, next to colleagues'
+containers); leave it unset in test/CI projects, where concurrent instances must
+never collide on a name. [CONCURRENCY.md](CONCURRENCY.md) has the exact
+conflict semantics.
+
 ### Locating packaged resources
 
 rosotacom is installed in an isolated environment (pipx, or a project venv), so

{rosotacom_dev-2.5.dev24 → rosotacom_dev-2.5.dev27}/docs/ci.md

@@ -48,6 +48,31 @@ The merge gate runs workflow lint, dependency/security review, runtime/build ass
 Python 3.10–3.14 are supported for the host CLI; Python 3.12 is the reference
 interpreter for packaging and Docker E2E jobs.
 
+### What the e2e slices wait for
+
+Every job in the gate starts at once — there is no runner contention — so the
+only thing that decides when the thirteen slices start is their `needs`. They
+wait for exactly two jobs:
+
+- **`image`**, because a slice adopts the published image rather than building
+  it, so it cannot start before that image is known to exist. On a hit this is
+  two manifest inspections, and it is what sets the floor.
+- **`quick-gate`**, `just lint && just typecheck` on one interpreter: the
+  cheapest signal that the tree is not obviously broken, so thirteen runners do
+  not spend seventy minutes discovering a syntax error. Four seconds of work,
+  sized to finish inside `image` and therefore free.
+
+They used to wait for `preflight-success`, which meant the whole five-version
+`merge-lightweight` matrix, and that cost **2.15 min of every gate run**.
+Measured against the sixty runs before #248, it had stopped an e2e round once,
+on `workflow-lint` — 0.12 min of the 2.15. Nothing about what may merge
+changed: `ci-success` still requires `workflow-lint`, `build-lint`,
+`merge-lightweight`, `package`, `quick-gate`, `image`, and `e2e`, and it is the
+only required check in branch protection.
+
+`tests/contract/test_workflow_contracts.py::test_e2e_waits_only_for_the_cheap_gate_and_the_image`
+keeps the barrier from growing back.
+
 ```bash
 just lint-workflows
 just lint-build
@@ -159,26 +184,35 @@ with a usage error, and a test owned twice fails
 
 The costs are warm pytest `call` durations — medians over seven merge-gate runs
 of 2026-08-11/12. On top of them each job pays a fixed
-`RUNNER_SETUP_SECONDS + IMAGE_BUILD_SECONDS` (2m05s: 55s of runner setup, then
+`RUNNER_SETUP_SECONDS + IMAGE_BUILD_SECONDS` (1m19s: 46s outside the tests, then
 the project image obtained inside whichever test runs first). Because that
 constant is per job and not per test, balancing warm costs balances wall clock.
 
 `IMAGE_BUILD_SECONDS` models the merge gate, where that image is pulled rather
 than built (see above); the release and nightly lanes still build and pay the
-older 154s. One slice does not currently reproduce its recorded split: `media`
-spends about 24s more than its two costs predict, and it is the critical path,
-so it is the first thing to remeasure.
+older 154s. It has now been re-measured twice, because both changes that made
+it smaller were changes to what a job moves rather than to what it runs: 154 →
+70 when #236 replaced the build with a pull, and 70 → 33 when #245 rebased the
+image on `ros-base` and the published project image went 1640 MB → 957 MB.
+Runs 31681061779 and 31687149587 ran the same partition either side of that, so
+the paired per-slice difference measures it directly: median −37.4s over all
+thirteen.
 
 ### How many slices
 
 `floor_seconds()` is `fixed + slowest single test` — the fastest any partition
 of this suite could be, because one job has to run that test and pays the fixed
-cost like every other. It is currently **6m32s**, of which 1m10s is the image
-(7m56s before #236 published it instead of rebuilding it per job).
-
-Thirteen slices sit at 7m14s, 1.11x the floor. That is the point of choosing N
-from the numbers rather than from taste: six balanced slices were 13m37s,
-twelve reach the floor, and past twelve every extra job is pure cost. The
+cost like every other. It is currently **5m47s**, of which 33s is the image
+(7m56s before #236 published it instead of rebuilding it per job, 6m32s before
+#245 shrank it).
+
+Thirteen slices sit at 6m26s, **1.12x** the floor. That is the point of choosing
+N from the numbers rather than from taste: six balanced slices were 13m37s,
+twelve reach the floor, and past twelve every extra job is pure cost. Note that
+1.12x is now a partition problem rather than a count problem — thirteen slices
+*can* reach 1.00x, and the current assignment does not, because `occupancy-grid`
+holds two 150s tests. The fixed cost falling twice is what exposed it: the same
+partition was 1.11x of a floor that was a minute and a half higher. The
 contract test asserts distance to the floor rather than the spread between
 slices — spread is compressed toward 1.0 by the fixed cost as N grows, so it
 keeps reading fine while the gate stops improving.