feat(studio-bridge): persistent sessions and Linux/Wine support (#669)

* chore(ci): add TypeScript lint/test scripts and dedicated typescript workflow

* chore(format): apply prettier to pre-existing TypeScript files for CI baseline

* chore: update pnpm lockfile and devcontainer for studio-bridge work

* feat(cli-output-helpers): add Reporter framework primitives and ResultReporter for single-result output

* refactor(auth): consolidate auth into nevermore-cli-helpers with cookie/ and open-cloud/ split

* feat(studio-bridge): add v2 protocol, transport, and persistent bridge host

* feat(studio-bridge): rewrite plugin template with action handlers, screenshot capture, PNG encoder

* feat(studio-bridge): add CLI commands (sessions, exec, run, query, screenshot, logs, plugin) with declarative grouping

* feat(studio-bridge): add persistent plugin manager

* refactor(template-helpers): add Linux fallback for rojo --plugin and prefix verbose log lines

* feat(studio-bridge): add Linux/Wine support and Docker image for headless E2E

* refactor(studio-bridge): drop v1 protocol path

* fix(studio-bridge): address review feedback (security, bugs, cleanup)

Security
- Use execFileSync with args arrays in FileResultReporter and
  linux-credential-writer instead of execSync + JSON.stringify quoting,
  which is not equivalent to shell quoting.
- Pass ROBLOSECURITY through the docker process env (via -e ROBLOSECURITY
  with no value) instead of baking it into argv, where it would be visible
  to ps on the host.
- Tighten ~/.nevermore/credentials.json to mode 0600 (and parent dir 0700).
- Use err.message instead of template-stringifying raw err in
  validateApiKeyAsync.
- Restore the terminal cursor in watch-renderer on render-callback errors
  and SIGINT/SIGTERM, instead of leaving the cursor hidden.

Bugs
- process run no longer drops the global --verbose flag; it reads the
  effective value via OutputHelper.isVerbose().
- exec/run resolve script file paths to absolute via path.resolve and
  switch from sync fs.readFileSync to async fs.readFile.
- explorer query honors --depth even when --descendants is not passed.
- process close (still a stub) returns success: false so the adapter
  exits non-zero.
- StudioBridgePlugin sends state "Edit" on register (was "ready", which
  is not a valid StudioState) and advertises the dynamically-dispatched
  capabilities (execute, queryState, captureScreenshot, queryDataModel,
  queryLogs).
- Persistent plugin install is now atomic: rojo builds into the temp
  build dir and the result is copyFile + rename'd into the plugins
  folder so Studio's polling watcher never observes a partial .rbxm.
- Plugin uninstall uses unlink-with-ENOENT-handling instead of a
  pre-check, removing a TOCTOU window.
- CompositeResultReporter teardown is failure-isolated via
  Promise.allSettled so a throwing reporter no longer skips siblings.
- DiscoveryStateMachine drops the dead _currentPort rotation logic
  (the field was set on construction but never advanced, so the
  rotation was a no-op anyway given parallel scanPortsAsync).
- png.luau asserts that dynamic-Huffman code 16 (repeat-previous) is
  not the first symbol; previously a malformed input would silently
  no-op into table.insert(nil) and spin the until-loop forever.

Cleanup
- Remove stale welcome / protocolVersion: 2 references left over from
  the v1 protocol drop in plugin-test templates and hand-off.test.ts;
  drop the matching "(v2)" suffix in describe and rename
  web-socket-protocol-v2.test.ts to web-socket-protocol.test.ts (the
  prior basic file becomes web-socket-protocol-basic.test.ts).
- Rename linux-display-manager sleep to sleepAsync per repo convention.
- Extract resolveScriptContentAsync (shared by exec and run) and
  colorizeState (shared by process list and process info).
- Combine duplicate getPersistentPluginPath imports in uninstall.ts.

CI
- Guard the new TS jobs' .npmrc _authToken= writes on $NPM_TOKEN /
  $GITHUB_TOKEN being non-empty, so fork PRs don't append empty
  _authToken= lines.
- Gate the studio-linux-ci "Diagnose Wine networking" step behind
  failure() instead of always() so it doesn't run on every successful PR.

* fix(studio-bridge): correlate plugin responses via PendingRequestMap

sendToPluginAsync attached a fresh ws.on('message', ...) listener per
call and matched the first non-heartbeat reply (or any error) when no
requestId was supplied. With ≥2 requests in flight this could (a) cross
responses between callers, (b) let an unrelated error reply satisfy a
real request, and (c) leak listeners until the EventEmitter MaxListeners
warning fired.

Replace the per-call pattern with a per-connection PluginConnectionState
that owns a PendingRequestMap. A single dispatcher is installed in
_registerPlugin; it routes plugin responses by requestId. Every outgoing
request must carry a requestId — all real callers (BridgeSession,
BridgeClient) already do; ensureRequestId is a defensive fallback.
Pending requests are cancelled on plugin disconnect, replacement, host
stopAsync, and shutdownAsync (graceful + force-close paths).

New unit tests in bridge-host.test.ts cover:
- concurrent in-flight requests resolve to the correct caller even when
  the plugin replies in reverse order
- an error reply with an unrelated requestId no longer satisfies a
  pending request (it now times out, as it should)
- pending requests reject when the plugin disconnects
- the dispatcher is installed once and does not accumulate listeners
  across many requests

All 669 TS tests + 158 plugin Lune tests pass.

* feat(studio-bridge): validate HostEnvelope action via zod schemas

Replace the unchecked `obj.action as ServerMessage` cast in decodeHostMessage
with a zod discriminated union covering all nine ServerMessage variants. A
buggy or hostile /client connection can no longer forward malformed actions
to the plugin. Adds nine targeted tests for missing/unknown action types,
wrong field types, and unknown error codes.

* test(studio-bridge): cover waitForSessionsToSettleAsync settle path

The settle path that gates cold-start commands had no direct test coverage —
all bridge-connection tests used keepAlive: true, which short-circuits the
settle in the constructor. Adds five targeted tests using the existing
options parameter to inject small timeouts: no-plugin firstSessionTimeout
exit, single-plugin settleMs quiet wait, settle timer reset on second
plugin, maxMs cap on continuous streams, and immediate return for client
role. Establishes a baseline before any settle-constant tuning.

* chore(studio-bridge): drop unused CommandRegistry.discoverAsync

cli.ts has always registered commands explicitly, and discoverAsync
(plus DiscoverOptions and the _tryImportAsync helper) was never wired
into production. Removes the convention-based loader, its barrel
re-export, and its seven unit tests. Net −245 / +4 lines.

* refactor(studio-bridge,cli-output-helpers): simplify single-result CLI output

The single-result output path had grown a 3-mode dispatch system (text |
table | json) plus a studio-bridge-specific base64 extension, all routed
through a thin format-output.ts wrapper that re-exported upstream types.
On inspection: every command's text and table formatters were literally
identical fns — text/table was a phantom distinction nobody used; base64
was a stdout pipeline strictly inferior to --output file.png.

Collapses the per-command `formatResult: { text, table, json }` dict to
two optional callbacks:

  cli.format(result) — human terminal output (also for --format=text)
  cli.json(result)   — overrides default formatJson, e.g. drop binary

Hoists reporter selection (Stdout/File/Watch dispatch) into a new
`buildResultReporter` factory in cli-output-helpers — the package that
owns the reporter classes — and inlines its construction in the adapter
handler, which is now mode-blind. Drops --format=base64 (binary file
output via -o is unaffected; binaryField + extractBinaryBuffer remain),
deletes the format-output.ts wrapper and its tests, and removes the
unused upstream output-mode module (OutputMode/resolveOutputMode no
longer have any callers). Updates tools/CLAUDE.md to match.

Net: −240 lines across the four formerly-separate refactor steps.

* chore(studio-bridge): emit apt manifest as Docker build artifact

Apt deps (winehq-stable, nodejs, gh, ...) in the studio-linux Docker
image aren't pinned to specific versions. That's a deliberate trade-off
versus the brittleness of "this exact apt version is no longer in the
repo," but it leaves drift across rebuilds invisible. Dumps a sorted TSV
of all installed packages and versions to /image-manifest-apt.tsv at
build time, then has the studio-linux-ci workflow extract and upload it
as a 90-day artifact. When a future rebuild mysteriously breaks Studio,
diffing the manifest against the last known-good build shows what
actually changed.

* refactor(studio-bridge): use EncodingService:Base64Encode for screenshot

Replaces the hand-rolled buffer-based base64 encoder (~60 lines, including
a 64-entry ASCII LUT and a localized hot loop) with a call to Roblox's
built-in EncodingService:Base64Encode. The native implementation is
faster than any Luau loop and removes a chunk of vendored encoding logic
we'd otherwise have to maintain. Resolves a code review note from Quenty.

* chore(vscode): enable file nesting for init.lua and sibling files

* docs(studio-bridge): trim programmatic API and protocol sections from README

* chore(ci): skip studio-linux-ci e2e when ROBLOSECURITY cookie is stale

Author: Quenty

.devcontainer/devcontainer.json

@@ -10,7 +10,8 @@
 			"version": "22",
 			"pnpmVersion": "10.27.0"
 		},
-		"ghcr.io/devcontainers/features/github-cli:1": {}
+		"ghcr.io/devcontainers/features/github-cli:1": {},
+		"ghcr.io/devcontainers/features/docker-in-docker:2": {}
 	},
 
 	"customizations": {

.github/workflows/studio-linux-ci.yml

@@ -0,0 +1,322 @@
+name: studio-linux-ci
+
+on:
+  schedule:
+    - cron: '0 3 * * *' # Nightly 03:00 UTC
+  workflow_dispatch:
+    inputs:
+      studio_version:
+        description: 'Override Studio version hash (leave empty for latest)'
+        required: false
+  push:
+    branches: [main]
+    paths:
+      - 'tools/studio-bridge/docker/**'
+      - 'tools/studio-bridge/src/**'
+      - '.github/workflows/studio-linux-ci.yml'
+  pull_request:
+    paths:
+      - 'tools/studio-bridge/docker/**'
+      - 'tools/studio-bridge/src/**'
+      - 'tools/nevermore-cli-helpers/src/auth/**'
+      - '.github/workflows/studio-linux-ci.yml'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: quenty/nevermore-studio-linux
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    outputs:
+      tag: ${{ steps.tag.outputs.tag }}
+    steps:
+      - name: Resolve Studio version
+        id: resolve
+        run: |
+          if [ -n "${{ inputs.studio_version }}" ]; then
+            VERSION="${{ inputs.studio_version }}"
+          else
+            VERSION=$(curl -s https://clientsettingscdn.roblox.com/v2/client-version/WindowsStudio64 | jq -r .clientVersionUpload)
+          fi
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "short=${VERSION:0:12}" >> "$GITHUB_OUTPUT"
+          echo "Resolved Studio version: $VERSION"
+
+          # Canary builds for PRs and non-main branches
+          BRANCH="${{ github.head_ref || github.ref_name }}"
+          if [ "$BRANCH" != "main" ]; then
+            BRANCH_SLUG="${BRANCH//\//-}"
+            SHORT_SHA="${GITHUB_SHA:0:8}"
+            echo "is_canary=true" >> "$GITHUB_OUTPUT"
+            echo "canary_tag=canary-${BRANCH_SLUG}-${SHORT_SHA}" >> "$GITHUB_OUTPUT"
+            echo "branch_tag=canary-${BRANCH_SLUG}" >> "$GITHUB_OUTPUT"
+            echo "Canary build: canary-${BRANCH_SLUG}-${SHORT_SHA}"
+          else
+            echo "is_canary=false" >> "$GITHUB_OUTPUT"
+            echo "canary_tag=" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Compute image tag for downstream jobs
+        id: tag
+        run: |
+          if [ "${{ steps.resolve.outputs.is_canary }}" = "true" ]; then
+            echo "tag=${{ steps.resolve.outputs.branch_tag }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=latest" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Check if image already exists
+        id: check
+        run: |
+          # Always rebuild canary images
+          if [ "${{ steps.resolve.outputs.is_canary }}" = "true" ]; then
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+            echo "Canary build — always rebuild"
+            exit 0
+          fi
+
+          if docker manifest inspect ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ steps.resolve.outputs.version }} > /dev/null 2>&1; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+            echo "Image already exists for version ${{ steps.resolve.outputs.version }}, skipping build"
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+            echo "Image not found, will build"
+          fi
+        env:
+          DOCKER_CLI_EXPERIMENTAL: enabled
+
+      - name: Checkout repository
+        if: steps.check.outputs.exists != 'true' || github.event_name == 'workflow_dispatch' || github.event_name == 'push'
+        uses: actions/checkout@v6
+
+      - name: Set up Docker Buildx
+        if: steps.check.outputs.exists != 'true' || github.event_name == 'workflow_dispatch' || github.event_name == 'push'
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GitHub Container Registry
+        if: steps.check.outputs.exists != 'true' || github.event_name == 'workflow_dispatch' || github.event_name == 'push'
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Compute image tags
+        if: steps.check.outputs.exists != 'true' || github.event_name == 'workflow_dispatch' || github.event_name == 'push'
+        id: tags
+        run: |
+          if [ "${{ steps.resolve.outputs.is_canary }}" = "true" ]; then
+            # Tag with both the SHA-specific and stable branch tags
+            TAGS="${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ steps.resolve.outputs.canary_tag }}
+          ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ steps.resolve.outputs.branch_tag }}"
+          else
+            TAGS="${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
+          ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ steps.resolve.outputs.version }}
+          ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ steps.resolve.outputs.short }}"
+          fi
+          echo "tags<<ENDOFTAGS" >> "$GITHUB_OUTPUT"
+          echo "$TAGS" >> "$GITHUB_OUTPUT"
+          echo "ENDOFTAGS" >> "$GITHUB_OUTPUT"
+
+      - name: Build and push image
+        if: steps.check.outputs.exists != 'true' || github.event_name == 'workflow_dispatch' || github.event_name == 'push'
+        uses: docker/build-push-action@v6
+        with:
+          context: tools/studio-bridge/docker
+          build-contexts: workspace=.
+          build-args: |
+            STUDIO_VERSION=${{ steps.resolve.outputs.version }}
+          push: true
+          tags: ${{ steps.tags.outputs.tags }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Extract image manifest
+        if: steps.check.outputs.exists != 'true' || github.event_name == 'workflow_dispatch' || github.event_name == 'push'
+        run: |
+          PRIMARY_TAG=$(printf '%s\n' "${{ steps.tags.outputs.tags }}" | head -n1)
+          docker pull "$PRIMARY_TAG"
+          docker run --rm --entrypoint cat "$PRIMARY_TAG" /image-manifest-apt.tsv > image-manifest-apt.tsv
+          wc -l image-manifest-apt.tsv
+
+      - name: Upload image manifest
+        if: steps.check.outputs.exists != 'true' || github.event_name == 'workflow_dispatch' || github.event_name == 'push'
+        uses: actions/upload-artifact@v4
+        with:
+          name: image-manifest-${{ steps.resolve.outputs.version }}-${{ steps.resolve.outputs.short }}
+          path: image-manifest-apt.tsv
+          retention-days: 90
+
+      - name: Clean up old images
+        if: steps.check.outputs.exists != 'true' && steps.resolve.outputs.is_canary != 'true'
+        continue-on-error: true
+        uses: snok/container-retention-policy@v3.0.0
+        with:
+          account: quenty
+          token: ${{ secrets.GITHUB_TOKEN }}
+          image-names: nevermore-studio-linux
+          cut-off: 30d
+          keep-n-most-recent: 5
+
+  e2e:
+    needs: build
+    if: github.event_name == 'pull_request' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    container:
+      image: ghcr.io/quenty/nevermore-studio-linux:${{ needs.build.outputs.tag }}
+      credentials:
+        username: ${{ github.actor }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+      options: --user studio --dns 8.8.8.8 --dns 8.8.4.4 --cap-add NET_RAW
+      env:
+        ROBLOSECURITY: ${{ secrets.ROBLOSECURITY }}
+    steps:
+      - name: Start display server and Wine networking
+        run: |
+          # GitHub Actions overrides the container ENTRYPOINT, so we must
+          # start Xvfb + openbox and refresh Wine networking manually.
+          echo "Wine prefix before Xvfb:"
+          ls -la $WINEPREFIX/system.reg $WINEPREFIX/user.reg 2>/dev/null || echo "  No prefix files at $WINEPREFIX"
+          ls -la /home/studio/.wine/system.reg 2>/dev/null || echo "  No prefix at /home/studio/.wine"
+
+          Xvfb "${DISPLAY:-:99}" -screen 0 1024x768x24 &
+          sleep 0.5
+          DISPLAY="${DISPLAY:-:99}" openbox &
+          sleep 0.5
+          # Re-detect network interfaces so Wine sees the runtime network
+          wineboot -u > /dev/null 2>&1 || true
+
+          echo "Wine ipconfig after wineboot -u:"
+          wine ipconfig /all 2>/dev/null || echo "  ipconfig failed"
+
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Install aftman tools
+        run: aftman install --no-trust-check
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup registries
+        run: |
+          if [ -n "$GITHUB_TOKEN" ]; then
+            echo -e "\n//npm.pkg.github.com/:_authToken=$GITHUB_TOKEN" >> .npmrc
+            echo -e "\n//npm.pkg.github.com/:_authToken=$GITHUB_TOKEN" >> ~/.npmrc
+          fi
+          if [ -n "$NPM_TOKEN" ]; then
+            echo -e "\n//registry.npmjs.org/:_authToken=$NPM_TOKEN" >> .npmrc
+            echo -e "\n//registry.npmjs.org/:_authToken=$NPM_TOKEN" >> ~/.npmrc
+          fi
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build all tools
+        run: pnpm -r --filter './tools/**' run build
+
+      - name: Install studio-bridge CLI
+        run: npm install --ignore-scripts --force -g .
+        working-directory: tools/studio-bridge
+
+      - name: Verify environment health (pre-auth)
+        run: studio-bridge linux status
+
+      - name: Diagnose Wine networking
+        if: failure()
+        run: |
+          echo "=== /etc/resolv.conf ==="
+          cat /etc/resolv.conf
+          echo ""
+          echo "=== Host DNS test (curl) ==="
+          curl -sI https://clientsettingscdn.roblox.com/ 2>&1 | head -5 || echo "curl failed"
+          echo ""
+          echo "=== /sys/class/net ==="
+          ls -la /sys/class/net/ 2>/dev/null || echo "/sys/class/net not accessible"
+          echo ""
+          echo "=== /proc/net/route ==="
+          cat /proc/net/route 2>/dev/null || echo "/proc/net/route not accessible"
+          echo ""
+          echo "=== /proc/net/if_inet6 ==="
+          cat /proc/net/if_inet6 2>/dev/null || echo "No IPv6 info"
+          echo ""
+          echo "=== Wine ipconfig (before wineboot -u) ==="
+          wine ipconfig /all 2>/dev/null || echo "wine ipconfig failed"
+          echo ""
+          echo "=== Running wineboot -u ==="
+          WINEDEBUG=+nsi wineboot -u 2>&1 | head -30 || echo "wineboot -u failed"
+          echo ""
+          echo "=== Wine ipconfig (after wineboot -u) ==="
+          wine ipconfig /all 2>/dev/null || echo "wine ipconfig failed"
+          echo ""
+          echo "=== Wine prefix files ==="
+          ls -la $WINEPREFIX/system.reg $WINEPREFIX/user.reg 2>/dev/null || echo "No Wine prefix files"
+
+      - name: Inject authentication
+        id: auth
+        if: ${{ env.ROBLOSECURITY != '' }}
+        shell: bash
+        run: |
+          set +e
+          studio-bridge linux inject-credentials --verbose 2>&1 | tee inject-output.txt
+          exit_code=${PIPESTATUS[0]}
+          set -e
+          if [ $exit_code -ne 0 ]; then
+            if grep -qE 'cookie is invalid or expired \(HTTP (401|403)\)' inject-output.txt; then
+              echo "::warning::ROBLOSECURITY cookie is stale (HTTP 401/403). Skipping execute step — rotate the secret to re-enable e2e."
+              echo "cookie_stale=true" >> "$GITHUB_OUTPUT"
+              exit 0
+            fi
+            exit $exit_code
+          fi
+        env:
+          ROBLOSECURITY: ${{ secrets.ROBLOSECURITY }}
+
+      - name: Execute script through Studio bridge
+        if: ${{ env.ROBLOSECURITY != '' && steps.auth.outputs.cookie_stale != 'true' }}
+        run: studio-bridge process run --verbose --timeout 60000 'print("E2E test passed!")'
+        timeout-minutes: 5
+        env:
+          ROBLOSECURITY: ${{ secrets.ROBLOSECURITY }}
+
+      - name: Print logs
+        if: always()
+        run: |
+          echo "=== Environment ==="
+          echo "DISPLAY=$DISPLAY WINEPREFIX=$WINEPREFIX STUDIO_DIR=$STUDIO_DIR HOME=$HOME"
+          echo "Xvfb running: $(pgrep -x Xvfb > /dev/null && echo yes || echo no)"
+          echo "openbox running: $(pgrep -x openbox > /dev/null && echo yes || echo no)"
+          echo "Wine procs: $(pgrep -c wine 2>/dev/null || echo 0)"
+          echo ""
+          echo "=== Wine log (last 100 lines) ==="
+          tail -100 /tmp/studio-bridge-wine.log 2>/dev/null || echo "No Wine log"
+          echo ""
+          echo "=== Studio logs ==="
+          find $WINEPREFIX/drive_c/users/ -name "*.log" -path "*/Roblox/logs/*" 2>/dev/null | head -5
+          tail -50 $WINEPREFIX/drive_c/users/*/AppData/Local/Roblox/logs/*.log 2>/dev/null || echo "No Studio logs"
+          echo ""
+          echo "=== Wine prefix check ==="
+          ls -la $WINEPREFIX/system.reg 2>/dev/null || echo "No system.reg at WINEPREFIX=$WINEPREFIX"
+          ls -la /home/studio/.wine/system.reg 2>/dev/null || echo "No system.reg at /home/studio/.wine"
+
+      - name: Upload logs
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: studio-bridge-logs
+          path: |
+            /tmp/studio-bridge-wine.log
+            /home/studio/.wine/drive_c/users/*/AppData/Local/Roblox/logs/
+          if-no-files-found: ignore