@bitseek/hermes-webui 0.1.0-beta.0

package/templates/systemd/hermes-webui.service

@@ -0,0 +1,13 @@
+[Unit]
+Description=Bitseek Hermes WebUI
+After=network.target
+
+[Service]
+Type=simple
+Environment=HERMES_HOME=%h/.hermes
+ExecStart=%h/.hermes/local-bundle/runtime/node/bin/node %h/.hermes/local-bundle/node-global/bin/hermes-webui start --foreground --port 8787
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=default.target

package/templates/windows/hermes-webui-task.ps1

@@ -0,0 +1,3 @@
+$Node = "$env:LOCALAPPDATA\hermes\local-bundle\runtime\node\node.exe"
+$Cli = "$env:LOCALAPPDATA\hermes\local-bundle\node-global\bin\hermes-webui.mjs"
+& $Node $Cli start --foreground --port 8787

package/vendor/agent-frontend-shell/.bitseek-source.json

@@ -0,0 +1,6 @@
+{
+  "repo": "adv-org/agent-frontend-shell",
+  "branch": "dev-zkp",
+  "commit": "36860bfd509554ac8e1a6b56c0dba36ba6692758",
+  "synced_at": "2026-06-02T04:40:48.989Z"
+}

package/vendor/agent-frontend-shell/.dockerignore

@@ -0,0 +1,7 @@
+.git
+.pytest_cache
+__pycache__
+*.pyc
+*.pyo
+tests/
+.env*

package/vendor/agent-frontend-shell/.env.docker.example

@@ -0,0 +1,89 @@
+# Hermes Web UI — Docker Compose configuration template
+#
+# Copy this file to `.env` next to your docker-compose.yml.
+# All variables are optional — Docker Compose substitutes defaults if unset.
+#
+#   cp .env.docker.example .env
+#   # edit values you care about, then:
+#   docker compose up -d
+
+# ──────────────────────────────────────────────────────────────────────────
+# UID / GID — host user mapping
+# ──────────────────────────────────────────────────────────────────────────
+# Critical when bind-mounting an EXISTING host directory (e.g. ~/.hermes).
+# The container runs as UID/GID and must match your host file ownership,
+# otherwise the container can't read your config.yaml or write sessions.
+#
+# Find yours:   id -u   (UID)   |   id -g   (GID)
+#
+# On macOS, UIDs start at 501 (not 1000), so you MUST set these.
+# On Linux, the default of 1000 usually matches the first interactive user.
+#
+# REPLACE THESE WITH YOUR ACTUAL VALUES (run `id -u` and `id -g`):
+UID=1000
+GID=1000
+
+# ──────────────────────────────────────────────────────────────────────────
+# Hermes home directory — single-container compose only
+# ──────────────────────────────────────────────────────────────────────────
+# Where on the host your config, sessions, skills, and state live.
+# Default: ~/.hermes (works for everyone with a standard install)
+# Override if your .hermes is elsewhere:
+# HERMES_HOME=/opt/hermes-data
+
+# ──────────────────────────────────────────────────────────────────────────
+# Workspace directory — single-container compose
+# ──────────────────────────────────────────────────────────────────────────
+# Path to your code/project directory. The WebUI's file browser shows
+# this at /workspace inside the container.
+# Default: ~/workspace
+# HERMES_WORKSPACE=/home/me/dev
+
+# ──────────────────────────────────────────────────────────────────────────
+# Password — protect remote access
+# ──────────────────────────────────────────────────────────────────────────
+# REQUIRED if you expose the container on anything other than 127.0.0.1.
+# Without a password, anyone who can reach the port can run commands as
+# the agent.
+# HERMES_WEBUI_PASSWORD=change-me-to-something-strong
+
+# ──────────────────────────────────────────────────────────────────────────
+# Permission handling for bind-mounted .hermes — advanced
+# ──────────────────────────────────────────────────────────────────────────
+# By default, the WebUI's startup credential-permission fixer enforces
+# 0600 mode on .env, auth.json, and similar credential files in HERMES_HOME.
+# This is the right behavior on a clean install, but it can clash with:
+#
+#   - Bind-mounting an EXISTING ~/.hermes whose .env is intentionally 0640
+#     (e.g. group-readable for a Docker user group)
+#   - HERMES_HOME_MODE configured at the agent level for a multi-user setup
+#
+# To bypass the WebUI's fixer entirely:
+# HERMES_SKIP_CHMOD=1
+#
+# OR to allow group bits while still stripping world-readable:
+# HERMES_HOME_MODE=0640
+#
+# ⚠️ MULTI-CONTAINER WARNING: HERMES_HOME_MODE has DIFFERENT semantics in
+# the WebUI vs. the agent image:
+#   - WebUI: credential FILE mode threshold (0640 = allow group bits)
+#   - Agent: HERMES_HOME *directory* mode (default 0700)
+# 0640 on a directory has NO execute bit, so the agent can't enter its own
+# home → broken. If you set HERMES_HOME_MODE for a multi-container setup,
+# use 0750 (group-traversable) or 0701 (x-only for non-owner traversal).
+# The compose files document both correctly per-service.
+
+# ──────────────────────────────────────────────────────────────────────────
+# Multi-container only — used by docker-compose.two-container.yml and
+# docker-compose.three-container.yml
+# ──────────────────────────────────────────────────────────────────────────
+# These compose files use named Docker volumes by default (recommended).
+# Set the variables above to your host UID/GID — both the agent container
+# (HERMES_UID/HERMES_GID) and the webui container (WANTED_UID/WANTED_GID)
+# are derived from $UID/$GID so files written by one are readable by the
+# other.
+#
+# If you switch to bind mounts (replacing `hermes-home: {}` with a `device:`
+# bind), ALL THREE containers must mount the SAME host path and run as the
+# SAME UID/GID. Mismatched UIDs → "Permission denied" → the WebUI crashes
+# on every HTTP request because it can't read its own auth signing key.

package/vendor/agent-frontend-shell/.env.example

@@ -0,0 +1,34 @@
+# Hermes Web UI -- local machine config template
+# Copy this to .env and fill in your values.
+# start.sh sources .env automatically if present.
+# All values are optional -- auto-discovery will fill in anything left blank.
+
+# Path to your hermes-agent checkout (the repo that contains run_agent.py)
+# HERMES_WEBUI_AGENT_DIR=/path/to/hermes-agent
+
+# Python executable to use (defaults to the agent venv if found)
+# HERMES_WEBUI_PYTHON=/path/to/python
+
+# Bind address (default: 127.0.0.1 -- loopback only, safe default)
+# HERMES_WEBUI_HOST=127.0.0.1
+
+# Port to listen on (default: 8787)
+# HERMES_WEBUI_PORT=8787
+
+# Where to store sessions, workspaces, and other state (default: ~/.hermes/webui)
+# HERMES_WEBUI_STATE_DIR=~/.hermes/webui
+
+# Default workspace directory shown on first launch
+# HERMES_WEBUI_DEFAULT_WORKSPACE=~/workspace
+
+# Optional model override. Leave unset to use the active Hermes provider default.
+# HERMES_WEBUI_DEFAULT_MODEL=
+
+# Base directory for all Hermes state (affects all paths above if set)
+# HERMES_HOME=~/.hermes
+
+# Path to your Hermes config.yaml (for toolsets and model config)
+# HERMES_CONFIG_PATH=~/.hermes/config.yaml
+
+# Display name for the assistant in the UI (default: Hermes)
+# HERMES_WEBUI_BOT_NAME=Hermes

package/vendor/agent-frontend-shell/.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# These are supported funding model platforms
+
+github: nesquena

package/vendor/agent-frontend-shell/.github/workflows/browser-smoke.yml

@@ -0,0 +1,42 @@
+name: Browser smoke
+
+# Headless page-load smoke: boots the real server.py (agent-free) and loads the
+# key pages in Chromium, failing on any console error or uncaught JS exception.
+# This catches the runtime-JS brick class (const-reassign, function/window
+# collision) that `node --check`, ESLint, and the mocked pytest suite cannot
+# see — they only manifest when a real browser executes the page.
+#
+# No secrets, no credentials: the server boots agent-free and the smoke script
+# strips every *_API_KEY from the environment before launch.
+
+on:
+  pull_request:
+    branches: [master]
+  push:
+    branches: [master]
+
+jobs:
+  browser-smoke:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+          cache-dependency-path: |
+            **/requirements*.txt
+            **/pyproject.toml
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install "pyyaml>=6.0" playwright
+          # Install only the Chromium browser + its system deps.
+          python -m playwright install --with-deps chromium
+
+      - name: Run browser smoke
+        run: python tests/browser_smoke.py

package/vendor/agent-frontend-shell/.github/workflows/docker-smoke.yml

@@ -0,0 +1,233 @@
+name: Docker smoke
+
+# Runtime smoke gate for Docker init logic.
+#
+# Background: v0.51.84 (PR #2470) shipped a startup-killing :ro mount + chown
+# interaction (EROFS under `set -e`) that 9 source-level pytest invariants +
+# 5800+ existing tests all passed. The independent reviewer caught it by eye.
+# This workflow closes that class of gap by actually `docker compose up`-ing
+# each variant against a real Docker daemon on the GHA runner.
+#
+# Scope (intentionally small for v1):
+#   - 3 compose variants (single, two-container, three-container)
+#   - For multi-container variants, rebuild the local Dockerfile and re-tag
+#     it as ghcr.io/nesquena/hermes-webui:latest BEFORE `up` so the PR's
+#     changes to docker_init.bash / Dockerfile actually execute. Without this
+#     the multi-container variants would pull the previous release from GHCR
+#     and silently miss every PR-level regression.
+#   - Pre-flight `docker compose config` job to catch schema/interpolation drift.
+#   - Reaper before each smoke run + trap on EXIT for orphan defence.
+#
+# Out of scope for v1 (per design review):
+#   - HERMES_WEBUI_SMOKE_TEST env flag in docker_init.bash (production-code footgun)
+#   - --user 60000:60000 (skips the chown branch we're protecting against)
+#   - Hadolint / yamllint (separate lint workflow, follow-up PR)
+#   - Local-runnable scripts/docker-smoke-test.sh (ship CI first, then iterate)
+#   - Podman runtime smoke (defer until a podman-specific bug ships)
+
+on:
+  pull_request:
+    branches: [master]
+    paths:
+      - 'Dockerfile'
+      - 'docker_init.bash'
+      - 'docker-compose*.yml'
+      - '.dockerignore'
+      - '.env.docker.example'
+      - '.github/workflows/docker-smoke.yml'
+  push:
+    branches: [master]
+    paths:
+      - 'Dockerfile'
+      - 'docker_init.bash'
+      - 'docker-compose*.yml'
+      - '.dockerignore'
+      - '.env.docker.example'
+      - '.github/workflows/docker-smoke.yml'
+  workflow_dispatch:
+
+# Fork PRs run with no secrets — that's the right model. Pin to least privilege.
+permissions:
+  contents: read
+
+jobs:
+  compose-config:
+    name: Compose config validation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Validate every compose file parses
+        run: |
+          set -euo pipefail
+          for f in docker-compose.yml docker-compose.two-container.yml docker-compose.three-container.yml; do
+            echo "::group::compose config: $f"
+            docker compose -f "$f" config > /dev/null
+            echo "::endgroup::"
+          done
+
+  # Build the Docker image once and cache layers via GHA cache.
+  # The smoke matrix jobs then pull from this cache instead of rebuilding
+  # from scratch, saving ~1-3 minutes per variant.
+  build-image:
+    name: Build Docker image (cache layers)
+    runs-on: ubuntu-latest
+    needs: compose-config
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: docker/setup-buildx-action@v3
+
+      - name: Build and cache Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          load: true
+          tags: ghcr.io/nesquena/hermes-webui:latest
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+  smoke:
+    name: Smoke ${{ matrix.variant }}
+    runs-on: ubuntu-latest
+    needs: [compose-config, build-image]
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        variant:
+          - single
+          - two-container
+          - three-container
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: docker/setup-buildx-action@v3
+
+      # Restore the cached Docker image from the build-image job.
+      # Read-only: the build-image job already populated the GHA cache, so the
+      # smoke variants only need cache-from (no redundant cache-to re-export).
+      - name: Restore Docker image from cache
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          load: true
+          tags: ghcr.io/nesquena/hermes-webui:latest
+          cache-from: type=gha
+
+      - name: Resolve compose file + project name
+        id: vars
+        run: |
+          set -euo pipefail
+          case "${{ matrix.variant }}" in
+            single)
+              echo "compose_file=docker-compose.yml" >> "$GITHUB_OUTPUT"
+              ;;
+            two-container)
+              echo "compose_file=docker-compose.two-container.yml" >> "$GITHUB_OUTPUT"
+              ;;
+            three-container)
+              echo "compose_file=docker-compose.three-container.yml" >> "$GITHUB_OUTPUT"
+              ;;
+          esac
+          # Per-run project name so concurrent jobs / reruns can't clobber each other.
+          echo "project=hermes-smoke-${{ matrix.variant }}-${{ github.run_id }}-${{ github.run_attempt }}" >> "$GITHUB_OUTPUT"
+
+      - name: Reap any prior hermes-smoke resources on this runner
+        run: |
+          set -euo pipefail
+          # Hosted GHA runners are fresh, so this is mostly defence-in-depth for
+          # self-hosted runner re-use. We rely primarily on the unique per-run
+          # project name + `compose down -v --remove-orphans` in the EXIT trap
+          # to clean up the resources THIS run creates; this step only sweeps
+          # leftovers from prior runs that crashed before their trap fired.
+          # Match by project-name prefix instead of labels (the compose files
+          # don't carry hermes-smoke labels on their resources).
+          for c in $(docker ps -aq --filter "name=hermes-smoke-"); do
+            docker rm -f "$c" || true
+          done
+          for v in $(docker volume ls -q | grep "^hermes-smoke-" || true); do
+            docker volume rm -f "$v" || true
+          done
+          for n in $(docker network ls --format '{{.Name}}' | grep "^hermes-smoke-" || true); do
+            docker network rm "$n" || true
+          done
+
+      - name: Prepare ephemeral host paths
+        id: paths
+        run: |
+          set -euo pipefail
+          STATE_DIR="$(mktemp -d -t hermes-smoke-state-XXXXXX)"
+          WORK_DIR="$(mktemp -d -t hermes-smoke-work-XXXXXX)"
+          echo "state_dir=$STATE_DIR" >> "$GITHUB_OUTPUT"
+          echo "work_dir=$WORK_DIR" >> "$GITHUB_OUTPUT"
+          echo "Allocated:"
+          echo "  HERMES_HOME      = $STATE_DIR"
+          echo "  HERMES_WORKSPACE = $WORK_DIR"
+
+      - name: Smoke (up + health + log scan + down)
+        env:
+          COMPOSE_FILE: ${{ steps.vars.outputs.compose_file }}
+          PROJECT: ${{ steps.vars.outputs.project }}
+          HERMES_HOME: ${{ steps.paths.outputs.state_dir }}
+          HERMES_WORKSPACE: ${{ steps.paths.outputs.work_dir }}
+        run: |
+          set -euo pipefail
+
+          # ----- Trap-guaranteed cleanup, regardless of exit reason -----
+          cleanup() {
+            local rc=$?
+            echo "::group::Cleanup (rc=$rc)"
+            docker compose -p "$PROJECT" -f "$COMPOSE_FILE" logs --no-color --tail=200 || true
+            docker compose -p "$PROJECT" -f "$COMPOSE_FILE" down -v --remove-orphans || true
+            rm -rf "$HERMES_HOME" "$HERMES_WORKSPACE" || true
+            echo "::endgroup::"
+            return $rc
+          }
+          trap cleanup EXIT
+
+          echo "::group::docker compose up"
+          # --wait blocks until all services report healthy OR --wait-timeout fires.
+          # Compose v2 returns nonzero on either failure mode.
+          docker compose -p "$PROJECT" -f "$COMPOSE_FILE" up -d --wait --wait-timeout 120
+          echo "::endgroup::"
+
+          echo "::group::container roster"
+          docker compose -p "$PROJECT" -f "$COMPOSE_FILE" ps
+          echo "::endgroup::"
+
+          # ----- WebUI /health probe -----
+          # Single-container: WebUI is on the host on 127.0.0.1:8787.
+          # Two/three-container: same — both compose files publish 127.0.0.1:8787.
+          echo "::group::Probe /health"
+          attempts=0
+          max_attempts=30
+          until curl --fail --silent --max-time 5 http://127.0.0.1:8787/health > /dev/null; do
+            attempts=$((attempts + 1))
+            if [ "$attempts" -ge "$max_attempts" ]; then
+              echo "❌ WebUI /health never returned 200 after $max_attempts attempts (~60s)"
+              exit 1
+            fi
+            sleep 2
+          done
+          echo "✅ /health = 200 after $attempts attempts"
+          echo "::endgroup::"
+
+          # ----- Startup log scan: must not contain any known-bad signatures -----
+          # These are the exact patterns that would have flagged #2470 in real time.
+          # The grep -i is anchored to actual error tokens; benign log lines that
+          # contain the substring 'error' in a stack-friendly context (e.g.
+          # "errorless", URL paths) are improbable for these specific tokens.
+          echo "::group::Startup log scan"
+          LOGS="$(docker compose -p "$PROJECT" -f "$COMPOSE_FILE" logs --no-color)"
+          # `!! ERROR` + `!! Exiting script` are the actual strings emitted by
+          # docker_init.bash's error_exit() helper — the function name itself
+          # never appears in output. The literal token `error_exit` is kept as
+          # a belt-and-suspenders catch for any stray debug/echo of the name.
+          BAD_PATTERNS='EROFS|Read-only file system|Traceback|PermissionError|!! ERROR|!! Exiting script|error_exit|groupmod: cannot|usermod: cannot|Failed to set (UID|GID|owner|permissions|ownership)'
+          if echo "$LOGS" | grep -E -i "$BAD_PATTERNS"; then
+            echo "❌ Startup logs contain known-bad pattern (see above)"
+            exit 1
+          fi
+          echo "✅ No known-bad patterns in startup logs"
+          echo "::endgroup::"

package/vendor/agent-frontend-shell/.github/workflows/native-windows-startup.yml

@@ -0,0 +1,132 @@
+name: Native Windows startup
+
+# Runs on PRs that touch start.ps1 (or this workflow). Validates the
+# native-Windows launch script catches the bug classes the recent
+# Windows-only batch caught manually (#2805 WOW64 ProgramFiles redirect,
+# #2806 venv-portability claim, #2807 port-parse + finally-cleanup).
+#
+# Scope (per nesquena-hermes comment on #2811 — option 1, mock-only):
+# hermes-agent is not published to PyPI, so we cannot pip-install it on
+# the runner. Instead we stub a hermes_cli/ directory next to a sibling
+# hermes-agent/ folder — just enough for start.ps1's existence guard to
+# pass. The workflow then runs start.ps1 for a few seconds and asserts
+# that none of start.ps1's own Write-Error guards fired. Server-boot
+# regressions remain covered by the Linux jobs and docker-smoke.yml.
+
+on:
+  pull_request:
+    paths:
+      - 'start.ps1'
+      - '.github/workflows/native-windows-startup.yml'
+  workflow_dispatch:
+
+jobs:
+  native-windows-startup:
+    name: start.ps1 path discovery (mock hermes-agent)
+    runs-on: windows-latest
+    timeout-minutes: 8
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      # Create the WebUI venv. start.ps1 prefers $AgentDir\venv if it
+      # exists, then falls back to the python on PATH. We create a
+      # WebUI-local venv to mirror the README's documented native path
+      # and to give start.ps1 a real python.exe to invoke.
+      - name: Create venv (README path)
+        shell: pwsh
+        run: |
+          python -m venv venv
+          if (-not (Test-Path venv\Scripts\python.exe)) {
+            throw "venv\Scripts\python.exe missing after venv create"
+          }
+
+      # Mock-only hermes-agent provisioning. We can't pip-install
+      # hermes-agent (not on PyPI), so we stub the minimum that
+      # start.ps1's `Test-Path hermes_cli -PathType Container` guard
+      # needs to pass. server.py would crash on this stub at import
+      # time — we deliberately do NOT probe /health below.
+      - name: Stub hermes-agent (mock hermes_cli only)
+        shell: pwsh
+        run: |
+          $agentDir = Join-Path (Split-Path -Parent $PWD) 'hermes-agent'
+          $cliDir = Join-Path $agentDir 'hermes_cli'
+          New-Item -ItemType Directory -Force -Path $cliDir | Out-Null
+          Set-Content -Path (Join-Path $cliDir '__init__.py') -Value '# stub for CI path-discovery test only'
+          "HERMES_WEBUI_AGENT_DIR=$agentDir" >> $env:GITHUB_ENV
+          Write-Host "Stub hermes-agent provisioned at $agentDir"
+
+      # Run start.ps1 and verify it passes its own discovery guards
+      # without erroring out. server.py will exit non-zero on the stub
+      # (no real CLI code) — that's expected and not asserted against.
+      # We only fail if start.ps1's own Write-Error guards fire.
+      - name: Run start.ps1 + verify path discovery
+        shell: pwsh
+        run: |
+          $stdout = Join-Path $env:RUNNER_TEMP 'start-ps1.out'
+          $stderr = Join-Path $env:RUNNER_TEMP 'start-ps1.err'
+          $proc = Start-Process -FilePath 'pwsh' `
+            -ArgumentList '-NoLogo','-File','.\start.ps1' `
+            -WorkingDirectory $PWD `
+            -PassThru `
+            -RedirectStandardOutput $stdout `
+            -RedirectStandardError  $stderr
+          "SERVER_PID=$($proc.Id)" >> $env:GITHUB_ENV
+          Write-Host "Spawned start.ps1 wrapper PID $($proc.Id)"
+
+          # Path discovery is sub-second; the 8s buffer lets the python
+          # launch land in the logs (and immediately exit on the stub).
+          Start-Sleep -Seconds 8
+
+          Write-Host "===== start.ps1 stdout ====="
+          $stdoutContent = if (Test-Path $stdout) { Get-Content $stdout -Raw } else { '<empty>' }
+          Write-Host $stdoutContent
+          Write-Host "===== start.ps1 stderr ====="
+          $stderrContent = if (Test-Path $stderr) { Get-Content $stderr -Raw } else { '<empty>' }
+          Write-Host $stderrContent
+
+          # Pattern set: every Write-Error message start.ps1 can emit on
+          # its own discovery path. If any of these appear in stderr,
+          # path discovery regressed and the job must fail.
+          $guardErrors = @(
+            'Python 3 is required',
+            'hermes-agent not found',
+            'HERMES_WEBUI_AGENT_DIR is set to',
+            'is not a valid integer port',
+            'is out of TCP-port range',
+            'server.py not found'
+          )
+          foreach ($msg in $guardErrors) {
+            if ($stderrContent -and $stderrContent -match [regex]::Escape($msg)) {
+              throw "REGRESSION: start.ps1 errored on guard '$msg' - path discovery failed."
+            }
+          }
+          Write-Host "OK: start.ps1 path discovery - all guards passed."
+
+      # taskkill /T walks the process tree, /F forces. taskkill returns
+      # 128 ("process not found") if the PID is already gone — that's
+      # the expected steady state for this mock-only workflow because
+      # server.py exits immediately on the stub hermes_cli. Reset
+      # $LASTEXITCODE so the step never fails on the cleanup itself.
+      - name: Stop background server (tree-kill)
+        if: always()
+        shell: pwsh
+        run: |
+          if ($env:SERVER_PID) {
+            & taskkill /PID $env:SERVER_PID /T /F 2>&1 | Out-Host
+            $global:LASTEXITCODE = 0
+          }
+          # Belt-and-suspenders: kill anything still bound to 8787.
+          $hanging = Get-NetTCPConnection -LocalPort 8787 -State Listen -ErrorAction SilentlyContinue
+          if ($hanging) {
+            foreach ($c in $hanging) {
+              try { Stop-Process -Id $c.OwningProcess -Force -ErrorAction Stop } catch {}
+            }
+          }
+          exit 0

package/vendor/agent-frontend-shell/.github/workflows/release.yml

@@ -0,0 +1,57 @@
+name: Release & Docker
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write   # required: create GitHub Release
+      packages: write   # required: push to ghcr.io
+
+    steps:
+      - uses: actions/checkout@v4
+
+      # Create GitHub Release from tag with auto-generated notes
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+
+      # Set up multi-arch build (QEMU + Buildx)
+      - uses: docker/setup-qemu-action@v3
+      - uses: docker/setup-buildx-action@v3
+
+      # Log in to GitHub Container Registry
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      # Extract tags from the git ref (supports vX.Y and vX.Y.Z formats)
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=match,pattern=v(\d+\.\d+(?:\.\d+)?),group=1
+            type=raw,value=latest
+
+      # Build and push multi-arch image (amd64 + arm64)
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          build-args: HERMES_VERSION=${{ github.ref_name }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max