remo-cli 4.3.3__tar.gz → 4.3.5__tar.gz

remo_cli-4.3.5/.github/codeql/codeql-config.yml

@@ -0,0 +1,21 @@
+name: "remo CodeQL config"
+
+# Scope the scan to code this repository actually ships.
+#
+# `docs/remo-web.html` is an 881 KB single-file design mockup produced by a
+# page bundler, checked in as the visual reference the console's design was
+# adopted from (cited by `frontend/src/theme/tokens.css` and
+# `frontend/src/state/workspace.ts`). It is not served by anything: no Pages
+# workflow publishes `docs/`, nothing links to it, and it is absent from both
+# the wheel and the container image. You open it from disk.
+#
+# Scanning it produced one alert (js/xss-through-dom) whose "DOM text" source
+# is the file's OWN embedded `<script type="__bundler/template">` literal,
+# read back at line 86 and handed to `DOMParser.parseFromString`. That is how
+# every self-unpacking bundle works; there is no external input anywhere in
+# the flow, and no origin to be cross-site against.
+#
+# Only the one file is excluded, not `docs/` -- `docs/examples/` holds real
+# cloud-init YAML, and anything executable added there later should be scanned.
+paths-ignore:
+  - docs/remo-web.html

remo_cli-4.3.5/.github/dependabot.yml

@@ -0,0 +1,75 @@
+version: 2
+updates:
+  # Python dependencies (pyproject.toml)
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+    # Let a new release settle before we bump to it, so we don't chase
+    # immediately-yanked or regression releases.
+    cooldown:
+      default-days: 7
+    groups:
+      # One PR per week with all minor/patch production deps bumped together.
+      production-minor-patch:
+        dependency-type: "production"
+        update-types:
+          - "minor"
+          - "patch"
+      # One PR per week with all minor/patch dev-only deps bumped together.
+      dev-minor-patch:
+        dependency-type: "development"
+        update-types:
+          - "minor"
+          - "patch"
+    # Major bumps still get individual PRs so they can be reviewed carefully.
+
+  # GitHub Actions workflow versions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+    cooldown:
+      default-days: 7
+    groups:
+      actions:
+        update-types:
+          - "minor"
+          - "patch"
+
+  # Docker base images. Two Dockerfiles ship images:
+  #   /Dockerfile        — the CLI image (python:3.13-slim)
+  #   /docker/Dockerfile — the remo-web service (node:24-slim, python:3.11-slim)
+  # Nothing watched these before, so a base image could sit on an unpatched
+  # tag indefinitely — the CVEs that matter for a container usually arrive via
+  # the base image, not via the app's own dependencies.
+  - package-ecosystem: "docker"
+    directories:
+      - "/"
+      - "/docker"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+    cooldown:
+      default-days: 7
+    groups:
+      docker-images:
+        update-types:
+          - "minor"
+          - "patch"
+    ignore:
+      # Dependabot picks the highest published tag and has no concept of
+      # Node's release lines. Left alone it proposed node:20-slim ->
+      # node:25-slim (#156): 25 is an odd-numbered "Current" release that
+      # never becomes LTS and went EOL on 2026-06-01, so that bump would have
+      # swapped one unpatched base image for another — the exact failure this
+      # ecosystem entry exists to prevent. Node majors are picked by hand
+      # instead, on the LTS cadence (even-numbered, each October). Minor and
+      # patch bumps, which carry the base-image CVE fixes, keep flowing.
+      - dependency-name: "node"
+        update-types: ["version-update:semver-major"]

{remo_cli-4.3.3 → remo_cli-4.3.5}/.github/workflows/ci.yml

@@ -143,9 +143,17 @@ jobs:
     name: Frontend (typecheck + unit + build)
     runs-on: ubuntu-latest
     # Fast, backend-free coverage of the SPA: tsc typecheck, the Vitest
-    # unit/component suite (frontend/src/**/*.test.ts), and a production build.
-    # The Playwright e2e suite (frontend/tests/e2e) is NOT run here — it needs a live
-    # `remo web serve` backend (REMO_E2E_BASE_URL); see playwright.config.ts.
+    # unit/component suite (frontend/src/**/*.test.ts), the browser geometry
+    # suite (frontend/tests/geometry), and a production build.
+    #
+    # The geometry suite runs here because it is self-contained: it serves a
+    # fixture page with Vite and answers the terminal API/WebSocket from inside
+    # the spec. It covers what jsdom structurally cannot — jsdom has no layout
+    # engine, so every element measures 0x0 and any assertion about the terminal
+    # grid fitting its box passes vacuously there.
+    #
+    # The Playwright e2e suite (frontend/tests/e2e) is still NOT run here — it needs
+    # a live `remo web serve` backend (REMO_E2E_BASE_URL); see playwright.config.ts.
     defaults:
       run:
         working-directory: frontend
@@ -154,7 +162,7 @@ jobs:
 
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
         with:
-          node-version: "20"
+          node-version: "24"
           cache: npm
           cache-dependency-path: frontend/package-lock.json
 
@@ -170,5 +178,13 @@ jobs:
       - name: Unit tests
         run: npm run test
 
+      # Chromium only — the geometry suite runs the same specs twice against it
+      # (WebGL and DOM renderers) and needs no other browser.
+      - name: Install Chromium for the geometry suite
+        run: npx playwright install --with-deps chromium
+
+      - name: Browser geometry tests
+        run: npm run test:geometry
+
       - name: Build
         run: npm run build

{remo_cli-4.3.3 → remo_cli-4.3.5}/.github/workflows/codeql.yml

@@ -37,6 +37,7 @@ jobs:
         with:
           languages: ${{ matrix.language }}
           build-mode: ${{ matrix.build-mode }}
+          config-file: .github/codeql/codeql-config.yml
 
       - name: Perform CodeQL Analysis
         uses: github/codeql-action/analyze@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6

{remo_cli-4.3.3 → remo_cli-4.3.5}/.github/workflows/release.yml

@@ -161,7 +161,7 @@ jobs:
         run: uv build
 
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # release/v1
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
 
   publish-image:
     # Publishes the remo-web container image that docker/compose.example.yml
@@ -186,7 +186,7 @@ jobs:
       - uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4
 
       - name: Log in to GHCR
-        uses: docker/login-action@af1e73f918a031802d376d3c8bbc3fe56130a9b0 # v4
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4
         with:
           registry: ghcr.io
           username: ${{ github.actor }}

{remo_cli-4.3.3 → remo_cli-4.3.5}/.github/workflows/smoke-test-cleanup.yml

@@ -20,7 +20,7 @@ jobs:
     timeout-minutes: 10
     steps:
       - name: Configure AWS credentials (OIDC)
-        uses: aws-actions/configure-aws-credentials@517a711dbcd0e402f90c77e7e2f81e849156e31d # v6
+        uses: aws-actions/configure-aws-credentials@e6de054238d6b7531b4efff3b6587d9aade6a06c # v6
         with:
           role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
           role-session-name: remo-cleanup-${{ github.run_id }}

{remo_cli-4.3.3 → remo_cli-4.3.5}/.github/workflows/smoke-test.yml

@@ -58,7 +58,7 @@ jobs:
         run: uv sync
 
       - name: Configure AWS credentials (OIDC)
-        uses: aws-actions/configure-aws-credentials@517a711dbcd0e402f90c77e7e2f81e849156e31d # v6
+        uses: aws-actions/configure-aws-credentials@e6de054238d6b7531b4efff3b6587d9aade6a06c # v6
         with:
           role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
           role-session-name: remo-ci-${{ github.run_id }}

remo_cli-4.3.5/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "4.3.5"
+}

{remo_cli-4.3.3 → remo_cli-4.3.5}/AGENTS.md

@@ -47,7 +47,7 @@ src/remo_cli/              # Python CLI package (src layout, hatchling build)
 ├── __main__.py            # python -m remo_cli entry point
 ├── cli/                   # Click command layer (parsing only, no business logic)
 │   ├── main.py            # Root CLI group; mounts one group per remo_cli.core.provider_registry.all_descriptors()
-│   ├── shell.py           # remo shell — registry-dispatched update_entry() (delegates to upgrade()); prompt names the exact `remo <type> upgrade <name>` it will run; unknown type/ssh handled explicitly (no silent no-op)
+│   ├── shell.py           # remo shell — pre-connect version check for EVERY host type; _run_tools_upgrade() dispatches to the provider's update_entry() (delegates to upgrade()) or, for type="ssh", providers/added.configure(); prompt names the exact `remo <type> upgrade <name>` / `remo configure <name>` it will run; unknown type raises (no silent no-op); an added host with no `~/.remo-version` marker connects silently (FR-011)
 │   ├── cp.py              # remo cp
 │   ├── added.py           # remo add / remo remove / remo configure — provider-neutral SSH host registration (014) and configure (022)
 │   ├── web.py             # remo web {serve,check,push,status,adopt} — serve/check lazy-import remo_cli.web.* (NFR-008); push/status/adopt use core/web_adopt + core/web_drift only (adopt is a deprecated alias for push)
@@ -121,6 +121,12 @@ frontend/                  # remo-web browser SPA (Vite + React + TypeScript)
 │   │                        #   + masterLayout.ts (pure pane geometry: uniform grid + master/stack tiling)
 │   ├── state/                # discovery.ts, workspace.ts (layout persisted to localStorage)
 │   └── terminal/              # RendererAdapter (seam), XtermRenderer (the one engine), TerminalConnection, keymap
+│                            #   + fitLoop.ts (the container->emulator->PTY fit, extracted so the
+│                            #   browser geometry suite drives the shipped code and not a copy)
+└── tests/
+    ├── e2e/               # Playwright console suite — needs a live `remo web serve` (REMO_E2E_BASE_URL)
+    └── geometry/          # Playwright terminal-geometry suite — no backend, gates CI
+        └── harness/       # Vite fixture mounting the REAL TerminalCard + paneLayout
 
 docker/                    # remo-web container packaging (010-web-session-interface, US4)
 ├── Dockerfile               # multi-stage: frontend build -> wheel build -> slim Python runtime
@@ -130,6 +136,12 @@ docker/                    # remo-web container packaging (010-web-session-inter
 ansible/                   # Ansible playbooks (invoked by Python via subprocess)
 ├── roles/
 │   ├── incus_bootstrap/
+│   ├── nested_docker/     # Hosts whose kernel refuses NESTED overlayfs mounts (OrbStack): a
+│   │   │                  #   native-snapshotter buildx builder + a devcontainer shim (#160/#171).
+│   │   │                  #   Gated on group_vars' docker_nested_overlayfs; no-op elsewhere
+│   │   └── templates/
+│   │       └── devcontainer-shim.sh.j2  # /usr/local/bin/devcontainer: picks DOCKER_BUILDKIT /
+│   │                                    #   COMPOSE_BAKE / updateUID per project, per invocation
 │   └── user_setup/
 │       └── templates/
 │           └── remo-host.sh.j2   # Versioned `remo-host` command (capabilities/sessions/attach)
@@ -228,6 +240,9 @@ cd frontend && npm ci
 npm run build                     # tsc -b && vite build -> frontend/dist
 npm run lint                      # tsc --noEmit
 npm run test                      # Vitest unit/component suite (jsdom, no backend)
+npm run test:geometry             # Playwright terminal-geometry suite (no backend; serves its own
+                                  #   fixture. jsdom has no layout engine, so this is the only place
+                                  #   the terminal grid is checked against the box that clips it)
 npm run test:e2e                  # Playwright (needs REMO_E2E_BASE_URL -> live remo web serve)
 ```
 
@@ -282,6 +297,7 @@ made conditional to get a build green — fix the code or amend the gate by PR.
 | Lint | `uv run ruff check src/remo_cli` | Code Style |
 | Types | `uv run mypy src/remo_cli` | Code Style |
 | Frontend | `cd frontend && npm run lint && npm run test && npm run build` | Code Style |
+| Browser geometry | `cd frontend && npm run test:geometry` | Terminal grid fits its box (jsdom cannot check this) |
 | Fish completion | `./tests/integration/fish_completion.sh` | Principle VI (completion runs, not just reads) |
 | Packaging | wheel install smoke, Docker amd64+arm64 | Distribution integrity |
 | Security | CodeQL, dependency review | Supply chain |
@@ -319,9 +335,9 @@ checking nothing.
 - Ansible 2.14+ / YAML: Follow standard conventions plus Constitution principles
 
 ## Recent Changes
+- issues #160/#171 — nested overlayfs (OrbStack): Made hosts whose kernel refuses NESTED overlayfs mounts able to build devcontainers at all. An OrbStack "machine" is a container on a shared kernel (rootfs is a btrfs subvolume under `/scon/containers/<id>`), not a VM, so Docker inside it is nested and an overlay mount is refused — and Docker 29 made the containerd overlayfs snapshotter the default, so a freshly-configured host lands on the broken path with nothing to steer it. `remo configure` completed cleanly, `remo-host` responded, `remo web push` reported capabilities OK, and then every BuildKit build died on the first `RUN` with `mount source: "overlay" … operation not permitted`, surfaced as an opaque devcontainer-CLI stack trace that read like a project problem. New `ansible/roles/nested_docker/`, included from `tasks/configure_dev_tools.yml` (so all five configure playbooks inherit it) behind `group_vars/all.yml`'s `docker_nested_overlayfs`, which keys off `-orbstack-` in `ansible_kernel` — NOT `/mnt/mac`, which is absent under `orb create --isolated` and would have silently skipped the fix on exactly the configuration a user picks for a cleaner VM. It runs after `user_setup`, and every buildx task carries `become_user: remo_user`: buildx state lives in `~/.docker/buildx`, so a builder created for root leaves `project-launch` just as broken as no builder. **Two halves, because one fix is not enough.** (1) #160: a `docker-container` builder (`remo-native`) whose buildkitd.toml selects the `native` snapshotter, which copies layers instead of overlaying them — correct, and materially slower; `--bootstrap` so a broken image pull fails the configure rather than surfacing days later, and the builder is *recreated* when buildkitd.toml changes because `buildx create` reads `--config` once and an edited file otherwise never reaches an existing builder. (2) #171: the devcontainer CLI shells out to two builders whose requirements here are mutually exclusive — `docker compose build` HONOURS `DOCKER_BUILDKIT=0` and drops to the classic builder, which rejects the `additional_contexts` the CLI injects to install Features, while `updateUID`'s plain `docker build` needs exactly that setting to avoid the daemon's embedded BuildKit. No global value is correct for both, so a shim decides per invocation from the project's own `devcontainer.json`: Compose → `DOCKER_BUILDKIT=1 COMPOSE_BAKE=1` (verified: `COMPOSE_BAKE` alone still fails) plus `--update-remote-user-uid-default never` on `up`/`build` only — the CLI rejects the flag on `exec`, which `project-launch` uses; anything else → `DOCKER_BUILDKIT=0`, argv untouched; both → `BUILDX_BUILDER=remo-native`, so a user changing their default builder cannot silently break every devcontainer. Three placement decisions the tests pin, each defending a *silent* failure: the shim installs to `/usr/local/bin/devcontainer`, NOT `~/.local/bin` (that directory is added to PATH inside `~/.bashrc`, which returns early for non-interactive shells — a shim there would miss `ssh host 'devcontainer up …'`, the exact case it exists to fix, while passing every interactive test); it calls the real CLI by absolute path, because `command devcontainer` resolves through PATH, finds the shim again and recurses; and it declines to skip `updateUID` unless the host UID matches `user_setup`'s 1000 pin, since skipping at any other UID would trade a broken build for silently unwritable bind mounts. `docker buildx install` was rejected as the "clean" general fix — the docker-container driver cannot resolve the local-only image `updateUID`'s `FROM $BASE_IMAGE` names. remo NAMES a hand-added global `DOCKER_BUILDKIT` but does not delete it (the operator's line, in a file remo has no managed block in — the #121 authorized_keys lesson), and reports both costs it cannot fix via the task NAME, since `_filter_line` suppresses `debug` bodies: slower builds, and `apt` inside a running container failing with `Invalid cross-device link` (which is why `playwright install --with-deps`, and so E2E browser tests, cannot work on such a host — easy to miss, because a well-written `postCreateCommand` treats it as non-fatal and `devcontainer up` still reports success). New `tests/unit/test_devcontainer_shim.py` renders the template and *executes* it against a stub CLI for every branch. New `docs/nested-overlayfs.md`. No registry schema change; no new runtime deps; no new CLI flag or tool toggle — it is a repair for the tools already selected, not another tool.
 - 022-configure-added-hosts: Made manually-added SSH hosts first-class by giving them the one thing `remo add` (014) never did — a configure path. New provider-neutral `remo configure NAME` runs a new generic `ansible/ssh_configure.yml` against a registry `type="ssh"` entry, so an added host finally gets `remo-host`/zellij/`project-launch` and stops sitting in the `remo web` rail permanently badged `no_remo_host` with zero session targets. **No refactor of the four provider plays**: the role list was already shared via `tasks/configure_dev_tools.yml`, so a fifth playbook inherits the whole toolchain — the change is purely additive. The new play is two plays: a `localhost` play that asserts (never defaults) `remo_ssh_host`/`remo_ssh_user`/`remo_ssh_port` and `add_host`s them onto `ansible_host`/`ansible_user`/`ansible_port`/`ansible_ssh_private_key_file`, then a play targeting that named group (NOT `hosts: all`, which would pick up `inventory/hosts.yml`'s `hetzner_server` and whose zero-host case exits rc 0 — a silent false success). Four decisions the tests pin, each defending a *silent* failure: the identity is `| default(omit)`, never `'~/.ssh/id_rsa'` (aws_configure.yml's anti-pattern — a path default offers the WRONG key); it is paired with an explicit `-o IdentitiesOnly=yes`, which ansible-core does not add for `private_key_file` (without it a busy agent hits MaxAuthTries and dies "Too many authentication failures" while the passed key is never tried); both `raw` pre-flight probes (python3, `sudo -n true`) set `become: false`, since `ansible.cfg` sets `become = True` globally and a sudo probe run THROUGH sudo proves nothing; and `remo_user` is bound to `remo_ssh_user` rather than `group_vars/all.yml`'s `"remo"` — everything `user_setup` installs lands in `/home/{{ remo_user }}/.local/bin` and discovery logs in as the REGISTERED user, so the default would install `remo-host` into a second account and leave the console still reporting `no_remo_host` after a "successful" configure (it also skips the UID-1000 displacement, which only fires when 1000's holder is someone else). Root is refused (UID-1000 pin), the prompt defaults to no, and remo never reboots a host it did not provision — it reports via the task NAME, since `_filter_line` suppresses `debug` bodies. `core/known_hosts.py` gains `guard_added_ssh_host_only`, the mirror of `guard_not_added_ssh_host`: a provider host is refused naming `remo <type> upgrade NAME`, because the five configure plays are not interchangeable and a mis-target would succeed while configuring wrongly. **Bug fix in the same change** (`core/web_adopt.py`): `remo web push` hardcoded port 22 in `scan_and_verify_host_key`'s `ssh-keyscan` and `_lookup_trusted_keys`' `ssh-keygen -F`, so an added host on another port was reported `skipped/unreachable` — `authorize_service_key` never ran — with a remediation blaming a host that was reachable, or, worse, a different machine answering on 22 had its keys pushed. New `known_hosts_lookup_key()` follows OpenSSH's record form (bare for 22, `[host]:port` otherwise; verified against the real binary — neither direction is forgiving), and `-p` is omitted for 22 so every provider host's argv is byte-identical. `providers/added.py`'s `_reject_unsafe_field` now also rejects Jinja delimiters (registry values become extra-vars, which Ansible templates on the CONTROL NODE), re-checked on the configure read path so pre-existing entries are covered. `web/discovery.py`'s `no_remo_host` remediation now names the real command per host type instead of "re-run configure", which for an added host pointed at nothing. No registry schema change; no new runtime deps.
 - 021-cli-plane-separation: Split the three-intent `remo <provider> update` verb into three single-intent verbs — `upgrade` (in-instance configure play only, zero provider-side writes, SC-001), `resize` (resource change only — the factory rejects a dimensionless invocation with a `PreconditionError` listing that provider's dimension flags, before dispatching to the provider), and `tag` (managed-marker write only, generated iff `supports_managed_marker`; read-before-write no-op when already tagged, `OperationFailedError` — not `create`'s warn-and-continue — on write failure, SC-002) — and moved `bootstrap` off the flat instance plane into a new descriptor-driven `host` subgroup (`remo {incus,proxmox} host bootstrap`, generated iff `host_commands` is non-empty; `CommandSpec` gained a `target: ArgumentSpec | None` field so host commands take the host positionally — incus optional/defaults to localhost, proxmox required). `core/provider_registry.py`: `ProviderDescriptor.update_options` removed, replaced by `upgrade_options`/`resize_dimensions`/`resize_options`/`tag_options`/`host_commands`; new `ArgumentSpec` dataclass. `cli/providers/factory.py`: `_build_update` replaced by `_build_upgrade`/`_build_resize`/`_build_tag`/`_build_host_group`; `_instance_argument` grew a `param` kwarg so the new verbs take `NAME` positionally (matching the provider impl's `name` kwarg) while `create`/`destroy`/`info` keep `--name`; `_resolve_entry_for_destroy`'s user-hint lookup is now descriptor-driven (reads `kwargs` under the `registry_fields` JSON key ending in `_user`) instead of a `"user"` literal. Every provider module split `update()` into `upgrade()`/`resize()`/`tag()` (marker-supporting providers only) reusing existing private helpers unchanged; `update_entry()` (the `remo shell` tools-update path) now delegates to `upgrade()`. Renamed `--user` → `--host-user` (incus) / `--node-user` (proxmox) everywhere it appears (`remo add --user`, a different flag, is unchanged). Made every printed remedy truthful (SC-003): the registry-migration tagging notice and `sync`'s "Mark permanently:" line now recommend `tag` (previously wrongly recommended `sync`/`update`, which never wrote the marker); `remo shell`'s version-mismatch prompt now names the exact `remo <type> upgrade <name>` command it will run. Breaking change, no shim, no registry schema change: `remo <type> update`, flat `bootstrap`, and the old `--user` spelling are all Click "unknown command"/"no such option" errors post-change. FakeProvider's descriptor gained `upgrade_options`/`resize_dimensions`/`tag_options`/one `host_commands` entry, proving the full new surface is descriptor-only (SC-005).
-- 020-openapi-type-generation: Made the FastAPI service the machine-checked source of truth for every shape the browser console consumes, and made drift a build failure with an actionable message — three moves, in dependency order. **(1) Contract completeness, declaration-only** (not one serialized byte moves): `web/api/hosts.py` annotates `InstanceOut.status`/`SessionTargetOut.zellij_state`/`devcontainer_running` with the existing closed domain enums (dropping the `.value` unwrapping — a `str`-Enum serializes identically) and adds `KnownProviderType(str, Enum)` (`incus`/`hetzner`/`aws`/`proxmox`, fixed to the built-in set per FR-004a — never derived from the live `provider_registry`, so a third-party provider install can't perturb the artifact) typed `KnownProviderType | str` (`anyOf[$ref, string]`, keeping the wire field open); new `ErrorEnvelope`/`HealthResponse`/`ReadinessResponse`/`MintPairingResponse`/`DetailResponse` response models declare what four previously-untyped routes (`/health`, `/ready`, `/pairing/mint`, `POST /terminals`) already return, with the `{"error": {...}}` envelope declared only on routes that actually return it (never on `pairing.py`, whose 403 is `{"detail": ...}`). **(2) Generate and consume**: new stdlib `scripts/export_openapi.py` exports `frontend/src/api/generated/openapi.json` (`create_app().openapi()`, `sort_keys=True` + trailing newline for byte-reproducibility) and `terminal-frames.json` (a new `web/frames.py`: six Pydantic control-frame models + `InboundFrame`/`OutboundFrame` discriminated unions, wrapped via `TypeAdapter(...).json_schema()` in a `{protocol: "remo-terminal.v1", frame_version: 1, ...}` envelope that versions independently of the REST contract); `openapi-typescript` v7 (exact-pinned frontend devDependency) generates `schema.d.ts`, and a small synthetic-OpenAPI wrapper (`frontend/scripts/generate-frame-types.mjs`) generates `terminal-frames.d.ts` (openapi-typescript itself only accepts genuine OpenAPI documents). `web/api/terminals.py`'s five ad-hoc `{"v": 1, ...}` WS control-frame dict literals are gone, replaced by typed `frames.py` model construction/validation — `_handle_control`'s silent-drop behavior for malformed JSON, non-object payloads, and unknown frame types is preserved exactly (the one place this refactor could have changed runtime behavior; dedicated tests cover it). `frontend/src/api/client.ts` replaced ~12 hand-declared service-shaped interfaces with `components["schemas"][...]` aliases (console-owned shapes — `ApiError`, `ServiceStatus`, the forward-auth re-auth path — stay hand-written); `frontend/src/components/providerMeta.ts` now keys a `Record<InstanceStatus | KnownProviderType, ...>` off the generated unions, so a new enum member is a compile error at the presentation mapping while an off-union runtime value still renders via a preserved fallback (FR-013a — deleting that fallback to "achieve exhaustiveness" is explicitly wrong). **(3) Gate it**: three drift checks modeled on `tests/unit/test_docs_structure.py`'s established shape (name the artifact, group findings by kind, close with the exact regeneration command and a dependency-bump note) — `tests/unit/test_schema_drift.py` (REST + frame freshness against the live Python app, `test` CI job) and `frontend/scripts/check-types-fresh.mjs` (regenerated `.d.ts` vs. checked-in, `frontend` CI job) — fail, never skip, and never write a tracked file. New `docs/maintaining-generated-types.md` documents the four generated artifacts (never hand-edited; internal build input, no external compatibility promise, FR-029) and how to read a failure. No registry schema change; no new service runtime dependency.
 Only the newest three entries live here — `update-agent-context.sh` discards the rest on every run. The complete history is archived in [`docs/feature-history.md`](docs/feature-history.md); move displaced entries there rather than letting the generator drop them.
 
 

{remo_cli-4.3.3 → remo_cli-4.3.5}/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [4.3.5](https://github.com/get2knowio/remo/compare/v4.3.4...v4.3.5) (2026-08-16)
+
+
+### Bug Fixes
+
+* **cli:** check the tools version on added SSH hosts too ([#178](https://github.com/get2knowio/remo/issues/178)) ([#179](https://github.com/get2knowio/remo/issues/179)) ([1727b72](https://github.com/get2knowio/remo/commit/1727b724faef9b5b994640c41e80c3ebb550d240))
+
+## [4.3.4](https://github.com/get2knowio/remo/compare/v4.3.3...v4.3.4) (2026-08-15)
+
+
+### Bug Fixes
+
+* **ansible:** make devcontainers buildable where nested overlayfs is refused ([#173](https://github.com/get2knowio/remo/issues/173)) ([d500ff0](https://github.com/get2knowio/remo/commit/d500ff0e6ee397822be36d6c2de4d6489f47aa2c)), closes [#160](https://github.com/get2knowio/remo/issues/160) [#171](https://github.com/get2knowio/remo/issues/171)
+* **web:** re-assert the terminal size so a dropped resize self-heals ([#174](https://github.com/get2knowio/remo/issues/174)) ([78b1dd4](https://github.com/get2knowio/remo/commit/78b1dd435a7305006c97eddf6817eaa624f9ab5b))
+* **web:** rename trusted_store so CodeQL stops reading a path as a secret ([#168](https://github.com/get2knowio/remo/issues/168)) ([d370ab6](https://github.com/get2knowio/remo/commit/d370ab661f7d1d988595645b9f91cbca82cd5fa4))
+* **web:** the push/adopt defect trio ([#157](https://github.com/get2knowio/remo/issues/157), [#158](https://github.com/get2knowio/remo/issues/158), [#159](https://github.com/get2knowio/remo/issues/159)) ([#166](https://github.com/get2knowio/remo/issues/166)) ([fe4bf31](https://github.com/get2knowio/remo/commit/fe4bf31d1acb8f9ca1efa5bddeee4f23e33668ee))
+
 ## [4.3.3](https://github.com/get2knowio/remo/compare/v4.3.2...v4.3.3) (2026-08-06)
 
 

{remo_cli-4.3.3 → remo_cli-4.3.5}/CLAUDE.md

@@ -47,7 +47,7 @@ src/remo_cli/              # Python CLI package (src layout, hatchling build)
 ├── __main__.py            # python -m remo_cli entry point
 ├── cli/                   # Click command layer (parsing only, no business logic)
 │   ├── main.py            # Root CLI group; mounts one group per remo_cli.core.provider_registry.all_descriptors()
-│   ├── shell.py           # remo shell — registry-dispatched update_entry() (delegates to upgrade()); prompt names the exact `remo <type> upgrade <name>` it will run; unknown type/ssh handled explicitly (no silent no-op)
+│   ├── shell.py           # remo shell — pre-connect version check for EVERY host type; _run_tools_upgrade() dispatches to the provider's update_entry() (delegates to upgrade()) or, for type="ssh", providers/added.configure(); prompt names the exact `remo <type> upgrade <name>` / `remo configure <name>` it will run; unknown type raises (no silent no-op); an added host with no `~/.remo-version` marker connects silently (FR-011)
 │   ├── cp.py              # remo cp
 │   ├── added.py           # remo add / remo remove / remo configure — provider-neutral SSH host registration (014) and configure (022)
 │   ├── web.py             # remo web {serve,check,push,status,adopt} — serve/check lazy-import remo_cli.web.* (NFR-008); push/status/adopt use core/web_adopt + core/web_drift only (adopt is a deprecated alias for push)
@@ -104,7 +104,7 @@ src/remo_cli/              # Python CLI package (src layout, hatchling build)
 │   ├── pairing.py              # In-memory, single-live, TTL'd pairing-code session manager replacing the static setup API token
 │   └── api/
 │       ├── hosts.py            # GET /api/v1/hosts, /sessions, POST /discovery/refresh
-│       ├── setup.py            # Token-gated /api/v1/setup/{status,identity,registry,verify} (011-web-adopt)
+│       ├── setup.py            # Pairing-gated /api/v1/setup/{status,identity,registry,verify,end} (011-web-adopt; `end` added by #158)
 │       ├── terminals.py        # POST/GET/DELETE /api/v1/terminals, WS /api/v1/terminals/{id}
 │       └── pairing.py          # POST /api/v1/pairing/{mint,end} — operator-auth-gated pairing-code control plane, outside the dormant setup router
 └── models/
@@ -121,7 +121,13 @@ frontend/                  # remo-web browser SPA (Vite + React + TypeScript)
 │   │                        #   + masterLayout.ts (pure pane geometry: uniform grid + master/stack tiling)
 │   ├── state/                # discovery.ts, workspace.ts (layout persisted to localStorage), settings.ts (display prefs: site light/dark mode, accent, fonts, terminal theme + per-target overrides)
 │   ├── terminal/              # RendererAdapter (seam), XtermRenderer (the one engine), TerminalConnection, keymap
+│   │                        #   + fitLoop.ts (the container->emulator->PTY fit, extracted so the
+│   │                        #   browser geometry suite drives the shipped code and not a copy)
 │   └── theme/                 # tokens.css (light-dark() palette, one pair per token), fonts.ts, terminalThemes.ts (8 terminal color schemes: a token-derived Remo Dark/Light pair the default 'auto' selection tracks, plus 6 curated third-party)
+└── tests/
+    ├── e2e/               # Playwright console suite — needs a live `remo web serve` (REMO_E2E_BASE_URL)
+    └── geometry/          # Playwright terminal-geometry suite — no backend, gates CI
+        └── harness/       # Vite fixture mounting the REAL TerminalCard + paneLayout
 
 docker/                    # remo-web container packaging (010-web-session-interface, US4)
 ├── Dockerfile               # multi-stage: frontend build -> wheel build -> slim Python runtime
@@ -131,6 +137,12 @@ docker/                    # remo-web container packaging (010-web-session-inter
 ansible/                   # Ansible playbooks (invoked by Python via subprocess)
 ├── roles/
 │   ├── incus_bootstrap/
+│   ├── nested_docker/     # Hosts whose kernel refuses NESTED overlayfs mounts (OrbStack): a
+│   │   │                  #   native-snapshotter buildx builder + a devcontainer shim (#160/#171).
+│   │   │                  #   Gated on group_vars' docker_nested_overlayfs; no-op elsewhere
+│   │   └── templates/
+│   │       └── devcontainer-shim.sh.j2  # /usr/local/bin/devcontainer: picks DOCKER_BUILDKIT /
+│   │                                    #   COMPOSE_BAKE / updateUID per project, per invocation
 │   └── user_setup/
 │       └── templates/
 │           └── remo-host.sh.j2   # Versioned `remo-host` command (capabilities/sessions/attach)
@@ -229,6 +241,9 @@ cd frontend && npm ci
 npm run build                     # tsc -b && vite build -> frontend/dist
 npm run lint                      # tsc --noEmit
 npm run test                      # Vitest unit/component suite (jsdom, no backend)
+npm run test:geometry             # Playwright terminal-geometry suite (no backend; serves its own
+                                  #   fixture. jsdom has no layout engine, so this is the only place
+                                  #   the terminal grid is checked against the box that clips it)
 npm run test:e2e                  # Playwright (needs REMO_E2E_BASE_URL -> live remo web serve)
 ```
 
@@ -283,6 +298,7 @@ made conditional to get a build green — fix the code or amend the gate by PR.
 | Lint | `uv run ruff check src/remo_cli` | Code Style |
 | Types | `uv run mypy src/remo_cli` | Code Style |
 | Frontend | `cd frontend && npm run lint && npm run test && npm run build` | Code Style |
+| Browser geometry | `cd frontend && npm run test:geometry` | Terminal grid fits its box (jsdom cannot check this) |
 | Fish completion | `./tests/integration/fish_completion.sh` | Principle VI (completion runs, not just reads) |
 | Packaging | wheel install smoke, Docker amd64+arm64 | Distribution integrity |
 | Security | CodeQL, dependency review | Supply chain |
@@ -320,9 +336,9 @@ checking nothing.
 - Ansible 2.14+ / YAML: Follow standard conventions plus Constitution principles
 
 ## Recent Changes
+- issues #160/#171 — nested overlayfs (OrbStack): Made hosts whose kernel refuses NESTED overlayfs mounts able to build devcontainers at all. An OrbStack "machine" is a container on a shared kernel (rootfs is a btrfs subvolume under `/scon/containers/<id>`), not a VM, so Docker inside it is nested and an overlay mount is refused — and Docker 29 made the containerd overlayfs snapshotter the default, so a freshly-configured host lands on the broken path with nothing to steer it. `remo configure` completed cleanly, `remo-host` responded, `remo web push` reported capabilities OK, and then every BuildKit build died on the first `RUN` with `mount source: "overlay" … operation not permitted`, surfaced as an opaque devcontainer-CLI stack trace that read like a project problem. New `ansible/roles/nested_docker/`, included from `tasks/configure_dev_tools.yml` (so all five configure playbooks inherit it) behind `group_vars/all.yml`'s `docker_nested_overlayfs`, which keys off `-orbstack-` in `ansible_kernel` — NOT `/mnt/mac`, which is absent under `orb create --isolated` and would have silently skipped the fix on exactly the configuration a user picks for a cleaner VM. It runs after `user_setup`, and every buildx task carries `become_user: remo_user`: buildx state lives in `~/.docker/buildx`, so a builder created for root leaves `project-launch` just as broken as no builder. **Two halves, because one fix is not enough.** (1) #160: a `docker-container` builder (`remo-native`) whose buildkitd.toml selects the `native` snapshotter, which copies layers instead of overlaying them — correct, and materially slower; `--bootstrap` so a broken image pull fails the configure rather than surfacing days later, and the builder is *recreated* when buildkitd.toml changes because `buildx create` reads `--config` once and an edited file otherwise never reaches an existing builder. (2) #171: the devcontainer CLI shells out to two builders whose requirements here are mutually exclusive — `docker compose build` HONOURS `DOCKER_BUILDKIT=0` and drops to the classic builder, which rejects the `additional_contexts` the CLI injects to install Features, while `updateUID`'s plain `docker build` needs exactly that setting to avoid the daemon's embedded BuildKit. No global value is correct for both, so a shim decides per invocation from the project's own `devcontainer.json`: Compose → `DOCKER_BUILDKIT=1 COMPOSE_BAKE=1` (verified: `COMPOSE_BAKE` alone still fails) plus `--update-remote-user-uid-default never` on `up`/`build` only — the CLI rejects the flag on `exec`, which `project-launch` uses; anything else → `DOCKER_BUILDKIT=0`, argv untouched; both → `BUILDX_BUILDER=remo-native`, so a user changing their default builder cannot silently break every devcontainer. Three placement decisions the tests pin, each defending a *silent* failure: the shim installs to `/usr/local/bin/devcontainer`, NOT `~/.local/bin` (that directory is added to PATH inside `~/.bashrc`, which returns early for non-interactive shells — a shim there would miss `ssh host 'devcontainer up …'`, the exact case it exists to fix, while passing every interactive test); it calls the real CLI by absolute path, because `command devcontainer` resolves through PATH, finds the shim again and recurses; and it declines to skip `updateUID` unless the host UID matches `user_setup`'s 1000 pin, since skipping at any other UID would trade a broken build for silently unwritable bind mounts. `docker buildx install` was rejected as the "clean" general fix — the docker-container driver cannot resolve the local-only image `updateUID`'s `FROM $BASE_IMAGE` names. remo NAMES a hand-added global `DOCKER_BUILDKIT` but does not delete it (the operator's line, in a file remo has no managed block in — the #121 authorized_keys lesson), and reports both costs it cannot fix via the task NAME, since `_filter_line` suppresses `debug` bodies: slower builds, and `apt` inside a running container failing with `Invalid cross-device link` (which is why `playwright install --with-deps`, and so E2E browser tests, cannot work on such a host — easy to miss, because a well-written `postCreateCommand` treats it as non-fatal and `devcontainer up` still reports success). New `tests/unit/test_devcontainer_shim.py` renders the template and *executes* it against a stub CLI for every branch. New `docs/nested-overlayfs.md`. No registry schema change; no new runtime deps; no new CLI flag or tool toggle — it is a repair for the tools already selected, not another tool.
 - 022-configure-added-hosts: Made manually-added SSH hosts first-class by giving them the one thing `remo add` (014) never did — a configure path. New provider-neutral `remo configure NAME` runs a new generic `ansible/ssh_configure.yml` against a registry `type="ssh"` entry, so an added host finally gets `remo-host`/zellij/`project-launch` and stops sitting in the `remo web` rail permanently badged `no_remo_host` with zero session targets. **No refactor of the four provider plays**: the role list was already shared via `tasks/configure_dev_tools.yml`, so a fifth playbook inherits the whole toolchain — the change is purely additive. The new play is two plays: a `localhost` play that asserts (never defaults) `remo_ssh_host`/`remo_ssh_user`/`remo_ssh_port` and `add_host`s them onto `ansible_host`/`ansible_user`/`ansible_port`/`ansible_ssh_private_key_file`, then a play targeting that named group (NOT `hosts: all`, which would pick up `inventory/hosts.yml`'s `hetzner_server` and whose zero-host case exits rc 0 — a silent false success). Four decisions the tests pin, each defending a *silent* failure: the identity is `| default(omit)`, never `'~/.ssh/id_rsa'` (aws_configure.yml's anti-pattern — a path default offers the WRONG key); it is paired with an explicit `-o IdentitiesOnly=yes`, which ansible-core does not add for `private_key_file` (without it a busy agent hits MaxAuthTries and dies "Too many authentication failures" while the passed key is never tried); both `raw` pre-flight probes (python3, `sudo -n true`) set `become: false`, since `ansible.cfg` sets `become = True` globally and a sudo probe run THROUGH sudo proves nothing; and `remo_user` is bound to `remo_ssh_user` rather than `group_vars/all.yml`'s `"remo"` — everything `user_setup` installs lands in `/home/{{ remo_user }}/.local/bin` and discovery logs in as the REGISTERED user, so the default would install `remo-host` into a second account and leave the console still reporting `no_remo_host` after a "successful" configure (it also skips the UID-1000 displacement, which only fires when 1000's holder is someone else). Root is refused (UID-1000 pin), the prompt defaults to no, and remo never reboots a host it did not provision — it reports via the task NAME, since `_filter_line` suppresses `debug` bodies. `core/known_hosts.py` gains `guard_added_ssh_host_only`, the mirror of `guard_not_added_ssh_host`: a provider host is refused naming `remo <type> upgrade NAME`, because the five configure plays are not interchangeable and a mis-target would succeed while configuring wrongly. **Bug fix in the same change** (`core/web_adopt.py`): `remo web push` hardcoded port 22 in `scan_and_verify_host_key`'s `ssh-keyscan` and `_lookup_trusted_keys`' `ssh-keygen -F`, so an added host on another port was reported `skipped/unreachable` — `authorize_service_key` never ran — with a remediation blaming a host that was reachable, or, worse, a different machine answering on 22 had its keys pushed. New `known_hosts_lookup_key()` follows OpenSSH's record form (bare for 22, `[host]:port` otherwise; verified against the real binary — neither direction is forgiving), and `-p` is omitted for 22 so every provider host's argv is byte-identical. `providers/added.py`'s `_reject_unsafe_field` now also rejects Jinja delimiters (registry values become extra-vars, which Ansible templates on the CONTROL NODE), re-checked on the configure read path so pre-existing entries are covered. `web/discovery.py`'s `no_remo_host` remediation now names the real command per host type instead of "re-run configure", which for an added host pointed at nothing. No registry schema change; no new runtime deps.
 - 021-cli-plane-separation: Split the three-intent `remo <provider> update` verb into three single-intent verbs — `upgrade` (in-instance configure play only, zero provider-side writes, SC-001), `resize` (resource change only — the factory rejects a dimensionless invocation with a `PreconditionError` listing that provider's dimension flags, before dispatching to the provider), and `tag` (managed-marker write only, generated iff `supports_managed_marker`; read-before-write no-op when already tagged, `OperationFailedError` — not `create`'s warn-and-continue — on write failure, SC-002) — and moved `bootstrap` off the flat instance plane into a new descriptor-driven `host` subgroup (`remo {incus,proxmox} host bootstrap`, generated iff `host_commands` is non-empty; `CommandSpec` gained a `target: ArgumentSpec | None` field so host commands take the host positionally — incus optional/defaults to localhost, proxmox required). `core/provider_registry.py`: `ProviderDescriptor.update_options` removed, replaced by `upgrade_options`/`resize_dimensions`/`resize_options`/`tag_options`/`host_commands`; new `ArgumentSpec` dataclass. `cli/providers/factory.py`: `_build_update` replaced by `_build_upgrade`/`_build_resize`/`_build_tag`/`_build_host_group`; `_instance_argument` grew a `param` kwarg so the new verbs take `NAME` positionally (matching the provider impl's `name` kwarg) while `create`/`destroy`/`info` keep `--name`; `_resolve_entry_for_destroy`'s user-hint lookup is now descriptor-driven (reads `kwargs` under the `registry_fields` JSON key ending in `_user`) instead of a `"user"` literal. Every provider module split `update()` into `upgrade()`/`resize()`/`tag()` (marker-supporting providers only) reusing existing private helpers unchanged; `update_entry()` (the `remo shell` tools-update path) now delegates to `upgrade()`. Renamed `--user` → `--host-user` (incus) / `--node-user` (proxmox) everywhere it appears (`remo add --user`, a different flag, is unchanged). Made every printed remedy truthful (SC-003): the registry-migration tagging notice and `sync`'s "Mark permanently:" line now recommend `tag` (previously wrongly recommended `sync`/`update`, which never wrote the marker); `remo shell`'s version-mismatch prompt now names the exact `remo <type> upgrade <name>` command it will run. Breaking change, no shim, no registry schema change: `remo <type> update`, flat `bootstrap`, and the old `--user` spelling are all Click "unknown command"/"no such option" errors post-change. FakeProvider's descriptor gained `upgrade_options`/`resize_dimensions`/`tag_options`/one `host_commands` entry, proving the full new surface is descriptor-only (SC-005).
-- 020-openapi-type-generation: Made the FastAPI service the machine-checked source of truth for every shape the browser console consumes, and made drift a build failure with an actionable message — three moves, in dependency order. **(1) Contract completeness, declaration-only** (not one serialized byte moves): `web/api/hosts.py` annotates `InstanceOut.status`/`SessionTargetOut.zellij_state`/`devcontainer_running` with the existing closed domain enums (dropping the `.value` unwrapping — a `str`-Enum serializes identically) and adds `KnownProviderType(str, Enum)` (`incus`/`hetzner`/`aws`/`proxmox`, fixed to the built-in set per FR-004a — never derived from the live `provider_registry`, so a third-party provider install can't perturb the artifact) typed `KnownProviderType | str` (`anyOf[$ref, string]`, keeping the wire field open); new `ErrorEnvelope`/`HealthResponse`/`ReadinessResponse`/`MintPairingResponse`/`DetailResponse` response models declare what four previously-untyped routes (`/health`, `/ready`, `/pairing/mint`, `POST /terminals`) already return, with the `{"error": {...}}` envelope declared only on routes that actually return it (never on `pairing.py`, whose 403 is `{"detail": ...}`). **(2) Generate and consume**: new stdlib `scripts/export_openapi.py` exports `frontend/src/api/generated/openapi.json` (`create_app().openapi()`, `sort_keys=True` + trailing newline for byte-reproducibility) and `terminal-frames.json` (a new `web/frames.py`: six Pydantic control-frame models + `InboundFrame`/`OutboundFrame` discriminated unions, wrapped via `TypeAdapter(...).json_schema()` in a `{protocol: "remo-terminal.v1", frame_version: 1, ...}` envelope that versions independently of the REST contract); `openapi-typescript` v7 (exact-pinned frontend devDependency) generates `schema.d.ts`, and a small synthetic-OpenAPI wrapper (`frontend/scripts/generate-frame-types.mjs`) generates `terminal-frames.d.ts` (openapi-typescript itself only accepts genuine OpenAPI documents). `web/api/terminals.py`'s five ad-hoc `{"v": 1, ...}` WS control-frame dict literals are gone, replaced by typed `frames.py` model construction/validation — `_handle_control`'s silent-drop behavior for malformed JSON, non-object payloads, and unknown frame types is preserved exactly (the one place this refactor could have changed runtime behavior; dedicated tests cover it). `frontend/src/api/client.ts` replaced ~12 hand-declared service-shaped interfaces with `components["schemas"][...]` aliases (console-owned shapes — `ApiError`, `ServiceStatus`, the forward-auth re-auth path — stay hand-written); `frontend/src/components/providerMeta.ts` now keys a `Record<InstanceStatus | KnownProviderType, ...>` off the generated unions, so a new enum member is a compile error at the presentation mapping while an off-union runtime value still renders via a preserved fallback (FR-013a — deleting that fallback to "achieve exhaustiveness" is explicitly wrong). **(3) Gate it**: three drift checks modeled on `tests/unit/test_docs_structure.py`'s established shape (name the artifact, group findings by kind, close with the exact regeneration command and a dependency-bump note) — `tests/unit/test_schema_drift.py` (REST + frame freshness against the live Python app, `test` CI job) and `frontend/scripts/check-types-fresh.mjs` (regenerated `.d.ts` vs. checked-in, `frontend` CI job) — fail, never skip, and never write a tracked file. New `docs/maintaining-generated-types.md` documents the four generated artifacts (never hand-edited; internal build input, no external compatibility promise, FR-029) and how to read a failure. No registry schema change; no new service runtime dependency.
 Only the newest three entries live here — `update-agent-context.sh` discards the rest on every run. The complete history is archived in [`docs/feature-history.md`](docs/feature-history.md); move displaced entries there rather than letting the generator drop them.
 
 

{remo_cli-4.3.3 → remo_cli-4.3.5}/CONTRIBUTING.md

@@ -104,7 +104,7 @@ pre-release, and publishes the prerelease to PyPI + GHCR (`latest` is never
 moved). Users can install with:
 
 ```bash
-curl -fsSL https://get2knowio.github.io/remo/install.sh | bash -s -- --pre-release
+curl -fsSL https://raw.githubusercontent.com/get2knowio/remo/main/install.sh | bash -s -- --pre-release
 ```
 
 > Prefer testing **without** publishing when you can — a local wheel or a
@@ -127,7 +127,7 @@ You do **not** bump the version or push a tag by hand for stable releases:
 
 Users install the stable release with:
 ```bash
-curl -fsSL https://get2knowio.github.io/remo/install.sh | bash
+curl -fsSL https://raw.githubusercontent.com/get2knowio/remo/main/install.sh | bash
 ```
 
 > **One-time setup — publish trigger:** the tag release-please creates must be
@@ -180,12 +180,24 @@ We use [Semantic Versioning](https://semver.org/):
 
 ## Updating the Installer
 
-When you modify `install.sh`:
+`install.sh` at the repo root is the one copy, served straight off `main`:
 
-1. The `sync-install.yml` workflow automatically copies it to `docs/install.sh`
-2. GitHub Pages serves the updated version at https://get2knowio.github.io/remo/install.sh
+```
+https://raw.githubusercontent.com/get2knowio/remo/main/install.sh
+```
+
+There is no publish step and no second copy to keep in sync — a merge to
+`main` *is* the deploy. Note the URL is pinned to `main`, not to a tag: users
+should always get the current installer, and pinning a *release* is what the
+script's own `--version` flag is for.
 
-No manual sync needed.
+Because it ships the instant it merges, treat a change to `install.sh` as a
+change to production: run `bash -n install.sh` at minimum, and prefer testing
+the raw URL from your own branch first —
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/get2knowio/remo/<your-branch>/install.sh | bash
+```
 
 ## Testing Changes
 
@@ -206,6 +218,6 @@ remo incus destroy test-container --yes --host <incus-host>
 ### Test Installer
 
 ```bash
-# Test from branch
-curl -fsSL https://get2knowio.github.io/remo/install.sh | bash -s -- --branch my-feature
+# Test the latest pre-release
+curl -fsSL https://raw.githubusercontent.com/get2knowio/remo/main/install.sh | bash -s -- --pre-release
 ```

{remo_cli-4.3.3 → remo_cli-4.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: remo-cli
-Version: 4.3.3
+Version: 4.3.5
 Summary: Remote development environment CLI
 License-Expression: MIT
 License-File: LICENSE
@@ -327,6 +327,13 @@ remo configure mybox --skip docker  # everything except Docker
 remo web push                       # authorize the web service on it
 ```
 
+Re-running it is how a configured host stays current — it refreshes
+`project-menu`, `remo-host`, `project-launch` and the rest of the toolchain, and
+applies system package updates. `remo shell` checks the version on connect and
+offers to run it for you when the host is behind, exactly as it does for
+provider hosts. A host you added but never configured is left alone: no marker,
+no prompt, straight into a login shell.
+
 #### Example: an OrbStack VM
 
 [`docs/examples/orbstack-cloud-init.yaml`](docs/examples/orbstack-cloud-init.yaml)
@@ -334,30 +341,76 @@ prepares an [OrbStack](https://orbstack.dev) VM on a Mac so `remo add` and
 `remo configure` work first time:
 
 ```bash
-orb create ubuntu remo-mbp -c docs/examples/orbstack-cloud-init.yaml
+orb create ubuntu remo-mbp -u orbadmin -c docs/examples/orbstack-cloud-init.yaml
+remo add mbp remo@<name-that-resolves> --verify
 ```
 
 It installs only what Ansible needs to connect and hand over — `remo configure`
-does the rest. It deliberately creates no user: OrbStack already makes one named
-after your macOS account holding UID 1000, and registering *that* user is what
-puts `remo-host` in the home directory the web service logs into, while skipping
-`user_setup`'s UID-1000 reassignment entirely.
-
-To reach the VM from anywhere — your workstation, a homelab box, or the
-`remo web` service — rather than only from its Mac, use
+does the rest. It creates a `remo` account at **UID 1000** and installs your key
+there, which is the account to register.
+
+`-u orbadmin` is not optional. OrbStack creates a Linux account named after your
+macOS user, pins it to your **macOS UID** (501, not 1000), and does so *after*
+cloud-init finishes — it will even renumber a cloud-init-created account that
+shares its name. Giving OrbStack a throwaway name to own leaves UID 1000 free.
+That matters because `user_setup` pins `remo_user` to UID 1000: register an
+account at any other UID and `remo configure` runs `usermod -u 1000` against the
+account Ansible is logged in as, which shadow-utils refuses to do for a user with
+running processes. Add `--isolated` too if you want a plain VM with no Mac file
+sharing; it is independent of the UID fix.
+
+**Which name to register.** An OrbStack VM is not on your LAN — it gets a static
+address on OrbStack's internal bridge, and OrbStack has no bridged/DHCP-from-your
+-router mode — so its own IP means nothing to any other machine. Three paths, in
+increasing reach:
+
+| From | Register | Notes |
+|------|----------|-------|
+| The Mac itself | `remo-mbp.orb.local` | OrbStack's DNS. Nothing to set up. |
+| Your LAN, or a VPN | `<your-mac>` | OrbStack forwards the VM's `:22` to the Mac and exposes it on every interface, so the Mac's name reaches the VM's sshd with nothing installed in the VM. |
+| Anywhere | `remo-mbp.<tailnet>.ts.net` | The Tailscale example below — needed only if you want the VM itself on the tailnet. |
+
+Prefer a **bare name** over an FQDN or an IP: it resolves through whichever
+search domain is up — your VPN's or your router's — so one entry keeps working
+as you move. That is why a registered host reads `"host": "dev1"`.
+
+Two gotchas on the middle row. It routes through the *Mac's* `:22`, so only one
+VM can own it (and it collides with macOS Remote Login) — for a second VM,
+change `Port` in the sshd drop-in and register `remo@<mac>:<port>`. And a Mac
+does not register itself in your router's DNS the way a Linux DHCP client does:
+macOS sends the DHCP hostname only when `HostName` is set, which it is not by
+default (`LocalHostName`, the mDNS `.local` name, is never sent, and Linux hosts
+generally cannot resolve `.local` at all). Fix it once with
+`sudo scutil --set HostName <name> && sudo ipconfig set en0 DHCP` — after which
+the address may change freely, since DNS follows it.
+If a VPN or a Tailscale exit node with LAN access claims OrbStack's subnet
+(`orb config get network.subnet4`), even the Mac-local path black-holes; check
+with `route -n get <vm-ip>`.
+
+**Devcontainer builds.** An OrbStack machine is a container on a shared kernel,
+so Docker inside it is nested and the kernel refuses the overlayfs mounts
+BuildKit's default snapshotter needs — without help, no devcontainer builds at
+all. `remo configure` detects this and provisions a `native`-snapshotter buildx
+builder plus a `devcontainer` shim that picks the right build environment per
+project; builds work, but are noticeably slower. Two limits it cannot fix —
+`apt` inside a running container, and therefore `playwright install --with-deps`
+— are covered in [`docs/nested-overlayfs.md`](docs/nested-overlayfs.md).
+
+To reach the VM from anywhere — including a `remo web` service that cannot reach
+your Mac — use
 [`docs/examples/orbstack-cloud-init-tailscale.yaml`](docs/examples/orbstack-cloud-init-tailscale.yaml)
 instead. Same file plus Tailscale; it prints the address to register on first
-boot. Register the MagicDNS name, **not** the OrbStack IP:
+boot:
 
 ```bash
-orb create ubuntu remo-mbp -c docs/examples/orbstack-cloud-init-tailscale.yaml
-remo add mbp <user>@remo-mbp.<your-tailnet>.ts.net --verify
+orb create ubuntu remo-mbp -u orbadmin -c docs/examples/orbstack-cloud-init-tailscale.yaml
+remo add mbp remo@remo-mbp.<your-tailnet>.ts.net --verify
 ```
 
-An OrbStack VM's own IP is reachable from its Mac and nowhere else, so a
-registry entry pointing at it is useless to a `remo web` service running
-anywhere else. Use an **ephemeral** auth key: cloud-init keeps your user-data
-on the VM's disk, so the key outlives the boot that used it.
+Use an **ephemeral** auth key: cloud-init keeps your user-data on the VM's disk,
+so the key outlives the boot that used it. Leaving the placeholder is fine —
+tailscaled still installs, and `sudo tailscale up` joins interactively with no
+credential on disk.
 
 `remo remove NAME [--yes]` deregisters an added host by deleting **only** the
 local registry entry — it makes no connection to and no change on the remote