feat(cloak): add -p cloak stealth-browser profile and auth-session support

Second of two commits on this branch, on top of the kimi batch. Adds the
CloakBrowser profile (#456) and the image/tag precedence fix it needs.

- cloak profile: `-p cloak` runs agents in a CloakBrowser image
  (Dockerfile.cloak, extends :rust) -- source-patched stealth Chromium,
  headed on Xvfb :99 + openbox, binary baked at build (auto-update off).
  Ships the deva-cloak skill, make build-cloak/test-cloak, a
  paths-filtered cloak-image.yml, and release :cloak / :vX.Y.Z-cloak tags.
- auth sessions: a persistent host profile mount (~/.config/deva/
  cloak-profile -> userDataDir) so a login survives container removal.
  Interactive login over VNC is on-demand and direct-reach on
  OrbStack/Linux -- the agent starts x11vnc and you connect at the
  container IP; --cloak-vnc is the Docker-Desktop fallback that publishes
  a loopback port. --cloak-browser is an optional always-on cloak-browserd
  daemon the agent attaches to over CDP.
- fix(precedence): env > config > -p > default, so an explicit -p beats a
  .deva DEVA_DOCKER_TAG (guarded by scripts/test-image-precedence.sh).

Not built/smoke-tested locally (container network blocks apt); release CI
builds the image on GitHub runners.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: lroolle

.dockerignore

@@ -31,6 +31,7 @@ compose.yaml
 
 # References directory (don't need in image)
 references/
+reference/
 
 # Claude trace logs
 .claude-trace/

.github/workflows/cloak-image.yml

@@ -0,0 +1,54 @@
+name: Cloak Image
+
+# Paths-filtered on purpose: the cloak build bakes a ~200MB Chromium binary,
+# too heavy for every PR. Nightly also skips cloak deliberately — it only
+# refreshes agent CLI versions, none of which live in the cloak layer.
+# Release builds and pushes the real :cloak tag.
+on:
+  pull_request:
+    branches: [ main ]
+    paths:
+      - "Dockerfile.cloak"
+      - "scripts/cloak-entrypoint.sh"
+      - "versions.env"
+      - ".github/workflows/cloak-image.yml"
+  push:
+    branches: [ main ]
+    paths:
+      - "Dockerfile.cloak"
+      - "scripts/cloak-entrypoint.sh"
+      - "versions.env"
+      - ".github/workflows/cloak-image.yml"
+
+jobs:
+  build-and-test:
+    name: Build and Test Cloak Image
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Load pinned versions
+        id: pins
+        shell: bash
+        run: |
+          set -euo pipefail
+          source ./scripts/version-pins.sh
+          load_version_pins
+          emit_github_outputs "$GITHUB_OUTPUT"
+
+      # Build on top of the published rust image: this validates the cloak
+      # layer itself without rebuilding the whole base/rust stack in CI.
+      - name: Build cloak image
+        run: |
+          make build-cloak-image \
+            IMAGE_NAME=deva-smoke \
+            CLOAK_TAG=ci-cloak \
+            RUST_IMAGE=ghcr.io/thevibeworks/deva:rust \
+            CLOAKBROWSER_WRAPPER_VERSION="${{ steps.pins.outputs.cloakbrowser_wrapper_version }}"
+
+      - name: Test cloak image
+        run: |
+          make test-cloak \
+            IMAGE_NAME=deva-smoke \
+            CLOAK_TAG=ci-cloak

.github/workflows/release.yml

@@ -55,6 +55,7 @@ jobs:
       ccx_version: ${{ steps.pins.outputs.ccx_version }}
       copilot_api_version: ${{ steps.pins.outputs.copilot_api_version }}
       playwright_version: ${{ steps.pins.outputs.playwright_version }}
+      cloakbrowser_wrapper_version: ${{ steps.pins.outputs.cloakbrowser_wrapper_version }}
       rust_toolchains: ${{ steps.pins.outputs.rust_toolchains }}
       rust_default_toolchain: ${{ steps.pins.outputs.rust_default_toolchain }}
       rust_targets: ${{ steps.pins.outputs.rust_targets }}
@@ -216,10 +217,60 @@ jobs:
             RUST_DEFAULT_TOOLCHAIN=${{ needs.load-version-pins.outputs.rust_default_toolchain }}
             RUST_TARGETS=${{ needs.load-version-pins.outputs.rust_targets }}
 
+  build-and-push-cloak:
+    name: Build and Push Cloak Profile Image
+    runs-on: ubuntu-latest
+    needs: [prepare, load-version-pins, build-and-push-rust]
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.prepare.outputs.release_tag }}
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata for cloak profile
+        id: meta-cloak
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=raw,value=${{ needs.prepare.outputs.release_tag }}-cloak
+            type=raw,value=cloak
+
+      - name: Build and push cloak image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: ./Dockerfile.cloak
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta-cloak.outputs.tags }}
+          labels: ${{ steps.meta-cloak.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          build-args: |
+            BASE_IMAGE=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ needs.prepare.outputs.release_tag }}-rust
+            CLOAKBROWSER_WRAPPER_VERSION=${{ needs.load-version-pins.outputs.cloakbrowser_wrapper_version }}
+
   release:
     name: Create GitHub Release
     runs-on: ubuntu-latest
-    needs: [prepare, build-and-push, build-and-push-rust]
+    needs: [prepare, build-and-push, build-and-push-rust, build-and-push-cloak]
     permissions:
       contents: write
     steps:
@@ -258,6 +309,10 @@ jobs:
           echo "- \`ghcr.io/${{ env.IMAGE_NAME }}:${RELEASE_TAG}-rust\`" >> release_notes.md
           echo "- \`ghcr.io/${{ env.IMAGE_NAME }}:rust\`" >> release_notes.md
           echo "" >> release_notes.md
+          echo "**Cloak Profile (CloakBrowser stealth Chromium, headed):**" >> release_notes.md
+          echo "- \`ghcr.io/${{ env.IMAGE_NAME }}:${RELEASE_TAG}-cloak\`" >> release_notes.md
+          echo "- \`ghcr.io/${{ env.IMAGE_NAME }}:cloak\`" >> release_notes.md
+          echo "" >> release_notes.md
           echo "## Supported Architectures" >> release_notes.md
           echo "" >> release_notes.md
           echo "- linux/amd64" >> release_notes.md

AGENTS.md

@@ -19,7 +19,6 @@ runtime is Linux.
 - $HOME is /home/deva (not /root). sudo works without password.
 - Pre-installed: Node.js, Python (use `uv`, not pip), Go, git,
   gh, make, curl. pip is NOT in PATH.
-- Docker is available (socket mounted from host).
-- System packages and build caches persist across sessions.
+- Ephemeral container. Installed packages will not persist.
 - Container details are in DEVA_* environment variables.
 <!-- /deva:container-context -->

CHANGELOG.md

@@ -23,6 +23,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   Makefile, Dockerfile(+rust), version-pins/upgrade/update scripts,
   ci/nightly/release workflows; tests added (release-utils registry,
   version-upgrade mock, install-tooling, and `test-kimi-auth.sh`).
+- cloak authenticated-session support (#456): composable pieces for logging
+  into sites inside the stealth browser. The session persists via a host
+  profile dir (`~/.config/deva/cloak-profile` -> Chromium `userDataDir`,
+  auto-mounted for either path below) so a login done once survives container
+  removal.
+  - Interactive login over VNC: on OrbStack/native Linux the host reaches the
+    container directly, so the agent starts `x11vnc` on the `:99` display on
+    demand and you connect at the container IP -- no flag, no port publish.
+  - `--cloak-vnc` (`DEVA_CLOAK_VNC=1`): Docker-Desktop fallback that publishes
+    the VNC display on a host-loopback port (there the container IP is not
+    routable). Auto-generates a VNC password (printed once) unless
+    `DEVA_CLOAK_VNC_PASSWORD` is set; the published port is fixed at container
+    create. Independent of `--cloak-browser`.
+  - `--cloak-browser` (`DEVA_CLOAK_BROWSER=1`): an always-on CloakBrowser
+    daemon (`cloak-browserd`) holds one headed, persistent browser on the
+    cloak display with a loopback CDP endpoint. The agent drives it via
+    `connectOverCDP(CLOAK_CDP_ENDPOINT)` -- the same live browser, not a
+    throwaway. Starts post-UID-remap in docker-entrypoint so profile files
+    match the mounted host owner.
+  Documented in the `deva-cloak` skill.
+- cloak profile (#456): `deva.sh -p cloak <agent>` runs agents in a new
+  image (`Dockerfile.cloak`, extends `:rust`) with CloakBrowser stealth
+  Chromium, headed on Xvfb `:99` + openbox. The Chromium binary is baked
+  at build time (hermetic, auto-update off); `CLOAKBROWSER_WRAPPER_VERSION`
+  in versions.env pins the wrapper and thereby Chromium. Ships the
+  `deva-cloak` skill (keyed off `DEVA_CLOAK=1`), `make build-cloak` /
+  `test-cloak` targets, a paths-filtered `cloak-image.yml` CI workflow,
+  and release pushes `:cloak` / `:vX.Y.Z-cloak` tags. Nightly skips cloak
+  on purpose — that layer contains no agent CLIs.
 
 ### Fixed
 - `--trace` launch killed by `cp: cannot create regular file
@@ -37,6 +66,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   test became the subshell's exit status and `set -e` killed every
   non-verbose traced launch right after the banner; the subshell now
   exits 0 explicitly.
+- image/tag precedence: a `.deva` config file setting `DEVA_DOCKER_TAG`
+  (or `DEVA_DOCKER_IMAGE`) silently overrode the real environment and made
+  CLI `-p` a no-op — `deva.sh -p cloak` with a config `DEVA_DOCKER_TAG=rust`
+  launched rust, and even `DEVA_DOCKER_TAG=cloak deva.sh ...` was clobbered
+  back to the config value. Precedence is now environment > config files >
+  `-p` profile > default, with explicit CLI `-p` beating a config-file tag.
+  Guarded by `scripts/test-image-precedence.sh` in CI.
 
 ## [0.16.0] - 2026-07-14
 

DEV-LOGS.md

@@ -13,11 +13,40 @@
 - Minimal markdown markers, no unnecessary formatting, minimal emojis.
 - Reference issue numbers in the format `#<issue-number>` for easy linking.
 
-# [2026-07-21] Dev Log: traced launches die silently in freshly built images #414
-- Why: after rebuilding images, every `--trace` launch died with "failed to launch ephemeral container" and no error.
+# [2026-07-21] Dev Log: cloak always-on browser + VNC + persistent profile #456
+- Why: three asks for auth sites in the cloak browser — (1) VNC auto-secured with a password, (2) an always-on browser the agent can drive freely, (3) mount what preserves the whole session to the host. Verified the load-bearing assumption first in a throwaway cloak container: a persistent CloakBrowser launched with `--remote-debugging-port` exposes a CDP endpoint a SEPARATE Playwright client reaches via connectOverCDP, drives, and the browser survives that client disconnecting. So one daemon can back both the human (VNC) and the agent (CDP).
 - What:
-  - The #414 flock rework ended the CA-install subshell on `[ "$VERBOSE" = "true" ] && echo ...`; with VERBOSE unset the failed test became the subshell's exit status, and under `set -e` the entrypoint died right after the agent banner — silently, only in freshly built images (the entrypoint is baked). Fix: explicit `exit 0` before the subshell closes. Verified A/B: baked image dies, overlay-fixed image runs `deva.sh claude --trace --rm -Q -- --version` end-to-end (cctrace MITM up, trace file written). Rebuild images to pick this up.
-- Result: traced launch verified live against the host daemon.
+  - scripts/cloak-browserd.mjs: daemon holding launchPersistentContext (headed :99, userDataDir, `--remote-debugging-port=9222 --remote-debugging-address=127.0.0.1`), relaunch-on-close, SIGTERM-clean. Absolute import of cloakbrowser (lives outside $CLOAK_APP_DIR). Verified end-to-end (daemon up → agent connectOverCDP drives it → persists after disconnect).
+  - docker-entrypoint.sh maybe_start_cloak_browser: starts the daemon AFTER setup_nonroot_user (post UID/GID remap) so the mounted profile is written as the host UID — starting it in cloak-entrypoint (pre-remap) would leave 1001-owned files the agent can't touch. Idempotent under flock + a CDP-port probe: boot (`tail -f /dev/null`) starts it once under PID 1's tree, later agent execs find it up and skip. Verified branch logic with mocks (gate off, port-up skip, start path).
+  - deva.sh: `--cloak-browser`/`DEVA_CLOAK_BROWSER` (env + CDP endpoint + auto-mount `~/.config/deva/cloak-profile`→`/home/deva/.cloak-profile`, first-writer-wins). `--cloak-vnc` implies it (blank display otherwise). setup_cloak_runtime = one image guard + one warning + correct order. VNC auto-password: generated when unset, printed once in the announce; the var name contains PASSWORD so deva's existing redaction masks it in --debug. announce_cloak_browser prints the CDP endpoint + host profile path.
+  - Bug caught in test: the VNC password gen `tr -dc ... </dev/urandom | head -c8` took SIGPIPE under `set -o pipefail` (head closes the pipe) → killed the whole launch. Fixed to read a finite `head -c 128 /dev/urandom` chunk then filter+cut. This is the [[feedback_bash_set_u_arrays]] family of set-flag footguns.
+  - Makefile test-cloak: assert x11vnc + `node --check` the daemon. Skill rewritten: always-on browser (agent uses connectOverCDP, NOT its own launch()), VNC login flow, exactly which dir to mount (userDataDir = whole session) and which NOT (/opt/cloakbrowser = baked binary).
+- Result: full dry-run matrix green (vnc implies browser+profile+port+auto-pass; browser-only no port; off-profile warns; explicit password respected). NOT verified here: x11vnc serving RFB and a live daemon inside the built image — this env's network 502s the apt mirrors so I can't rebuild/apt-install. `make build-cloak && make test-cloak` on the host confirms; the CDP daemon itself is proven against the existing image.
+
+# [2026-07-21] Dev Log: cloak VNC for authenticated sites #456 (initial VNC cut; extended by the always-on-browser entry above)
+- Why: cloak agents need to reach sites behind a login. You can't mount the host's Chrome cookies — macOS encrypts cookie values with a Keychain key the Linux container can't reach, so the DB is undecryptable inside deva. And the interactive part of a login (MFA, captcha) needs a human at a real display, which headed-on-Xvfb doesn't offer. Verified the two load paths in the live container first: `launchContext({contextOptions:{storageState}})` loads (top-level `storageState` is silently dropped — a footgun, documented), and `launchPersistentContext({userDataDir})` persists cookies-with-expiry across reopens (session cookies are memory-only).
+- What: opt-in VNC into the cloak Xvfb display so a human logs in once, then a mounted profile carries the session to later headless runs.
+  - Dockerfile.cloak: +x11vnc in the apt layer.
+  - cloak-entrypoint.sh: when DEVA_CLOAK_VNC=1, start `x11vnc -display :99 -rfbport 5900 -forever -shared -bg`. Binds 0.0.0.0 in-container ON PURPOSE — the boundary is deva publishing to host loopback only; -localhost would make docker's port-proxy unreachable. DEVA_CLOAK_VNC_PASSWORD → -rfbauth, else -nopw with a loud warning.
+  - deva.sh: `--cloak-vnc` flag (+ DEVA_CLOAK_VNC env), setup_cloak_vnc probes a free host port from 5900 and publishes `-p 127.0.0.1:PORT:5900` + passes the env in; guarded to the cloak image; announce_cloak_vnc prints the URL and warns when attaching to a warm container that was created without the port (reachability is fixed at create, same constraint as the trace UI).
+- Result: dry-run matrix verified (port+env only with -p cloak + vnc; off-profile warns; free-port probe skips a busy 5900→5901). Entrypoint VNC block branch/args verified via a mocked x11vnc (-nopw vs -storepasswd/-rfbauth). NOT verified here: x11vnc actually serving RFB — this env's network 502s the apt mirrors so x11vnc can't be installed/rebuilt in-container; confirm on the host rebuild (`make build-cloak`).
+
+# [2026-07-21] Dev Log: traced launches dead + -p cloak no-op — two field breakages
+- Why: after rebuilding images, every `--trace` launch died with "failed to launch ephemeral container" and no error; and `-p cloak` (and even env `DEVA_DOCKER_TAG=cloak`) kept launching the rust image when `~/.config/deva/.deva` pinned `DEVA_DOCKER_TAG=rust`.
+- What:
+  - Trace: the #414 flock rework ended the CA-install subshell on `[ "$VERBOSE" = "true" ] && echo ...`; with VERBOSE unset the failed test became the subshell's exit status, and under `set -e` the entrypoint died right after the agent banner — silently, only in freshly built images (the entrypoint is baked). Fix: explicit `exit 0` before the subshell closes. Verified A/B: baked image dies, overlay-fixed image runs `deva.sh claude --trace --rm -Q -- --version` end-to-end (cctrace MITM up, trace file written). Rebuild images to pick this up.
+  - Precedence: `apply_config_value` unconditionally clobbered `DEVA_DOCKER_IMAGE/TAG` and set `*_ENV_SET=true`, so config files beat the real environment and `resolve_profile` treated `-p` as already-satisfied. Now `*_SOURCE` (env|config) is tracked: config never overrides env, and an explicit CLI `-p` (new `PROFILE_FROM_CLI`) overrides a config-sourced tag. Contract: environment > config files > `-p` > default. scripts/test-image-precedence.sh pins all four cases and runs in CI; it `env -u`s the deva container's own `DEVA_DOCKER_TAG` so the harness env can't fake results — which is exactly how the bug hid in earlier dry-run smokes.
+- Result: both repro commands (`deva -p cloak`, `DEVA_DOCKER_TAG=cloak deva -p cloak claude` with a rust-pinned config) now resolve `:cloak`; traced launch verified live against the host daemon.
+
+# [2026-07-20] Dev Log: cloak profile — CloakBrowser stealth Chromium image #456
+- Why: agents in the sandbox need a browser that passes bot detection (Cloudflare, FingerprintJS, reCAPTCHA scoring); plain Playwright headless in the rust image fails those checks. CloakBrowser is a source-patched Chromium with the same Playwright API — run it headed on a virtual display inside the container.
+- What:
+  - Dockerfile.cloak extends :rust: apt layer (xvfb/openbox/xdotool + anti-bot font packages), wrapper+playwright-core installed into CLOAK_APP_DIR=/opt/cloak (not global — bare ESM specifiers don't resolve from a global install), `cloakbrowser install` bakes the Chromium binary at build time with auto-update off (hermetic; the free v146 binary stays on GitHub Releases forever). Kept tini as PID 1 and restated `CMD ["claude"]` — redeclaring ENTRYPOINT resets the inherited CMD.
+  - cloak-entrypoint.sh: clean stale X locks, Xvfb :99 (1920x1080x24), poll display-ready via xdotool (bounded ~10s), openbox for --start-maximized, then exec docker-entrypoint.sh.
+  - deva.sh: `-p cloak` profile, ghcr tag `cloak`, local-tag fallback cloak > rust > latest; skills/deva-cloak documents agent-side usage (DEVA_CLOAK=1 marker, run from $CLOAK_APP_DIR).
+  - Version pin CLOAKBROWSER_WRAPPER_VERSION (wrapper hardcodes per-arch Chromium versions, so it pins Chromium too) wired through versions.env, Makefile (+VERSION_QUERY_OVERRIDES), version-pins.sh VERSION_PIN_VARS, update-version-pins.sh heredoc+refresh — the first draft omitted the heredoc entry, so `make versions-pin` would have silently deleted the pin.
+  - CI: paths-filtered cloak-image.yml builds on ghcr :rust and runs make test-cloak; release pushes :cloak and :vX.Y.Z-cloak (BASE_IMAGE = the release's -rust tag). Nightly skips cloak: that layer has no agent CLIs, and the ~200MB Chromium bake would double nightly cost for nothing.
+- Result: cloak rides feat/kimi-agent (#455) — bundling two features on one branch violates our one-branch-per-issue rule; noted for the PR split. Build verified via docker on the host socket; test-cloak asserts cloakbrowser info + display geometry.
 
 # [2026-07-20] Dev Log: add kimi agent (Moonshot Kimi Code CLI) #455
 - Why: Moonshot shipped an official coding-agent CLI (@moonshot-ai/kimi-code, bin `kimi`); deva should launch it like claude/codex/gemini/grok. Traced the grok integration (commit 93a59e0) via ccx as the template.