Hermes-agent

tests/docker/conftest.py

@@ -0,0 +1,139 @@
+"""Shared fixtures for docker-image integration tests.
+
+Tests in this directory build the image with the current ``Dockerfile``
+and exercise it via ``docker run``. They skip when Docker is unavailable
+(e.g. on developer laptops without a daemon).
+
+Override the image with ``HERMES_TEST_IMAGE`` env var to point at a pre-built
+image (faster local iteration); otherwise the ``built_image`` fixture builds
+the repo's Dockerfile once per session.
+
+Docker tests need longer timeouts than the suite default (30s), so every
+test under this directory is granted a 180s default via
+``pytest.mark.timeout`` applied at collection time.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from collections.abc import Iterator
+
+import pytest
+
+IMAGE_TAG = os.environ.get("HERMES_TEST_IMAGE", "hermes-agent-harness:latest")
+
+
+def _docker_available() -> bool:
+    """Return True iff a docker CLI is on PATH and the daemon answers."""
+    if shutil.which("docker") is None:
+        return False
+    try:
+        r = subprocess.run(
+            ["docker", "info"], capture_output=True, timeout=5,
+        )
+        return r.returncode == 0
+    except (subprocess.TimeoutExpired, OSError):
+        return False
+
+
+def pytest_collection_modifyitems(config, items):  # noqa: D401 - pytest hook
+    """Apply docker-suite policy: timeout bump + skip on missing docker."""
+    docker_ok = _docker_available()
+    skip_docker = pytest.mark.skip(
+        reason="Docker not available or daemon not running",
+    )
+    extend_timeout = pytest.mark.timeout(180)
+    for item in items:
+        if "tests/docker/" not in str(item.fspath).replace(os.sep, "/"):
+            continue
+        item.add_marker(extend_timeout)
+        if not docker_ok:
+            item.add_marker(skip_docker)
+
+
+@pytest.fixture(scope="session")
+def built_image() -> str:
+    """Build the image once per test session.
+
+    Override with ``HERMES_TEST_IMAGE`` env var to point at a pre-built
+    image (faster local iteration).
+    """
+    if os.environ.get("HERMES_TEST_IMAGE"):
+        return IMAGE_TAG
+    repo_root = os.path.abspath(
+        os.path.join(os.path.dirname(__file__), "..", ".."),
+    )
+    result = subprocess.run(
+        ["docker", "build", "-t", IMAGE_TAG, repo_root],
+        capture_output=True, text=True, timeout=1200,
+    )
+    assert result.returncode == 0, (
+        f"docker build failed:\n{result.stderr[-2000:]}"
+    )
+    return IMAGE_TAG
+
+
+@pytest.fixture
+def container_name(request) -> Iterator[str]:
+    """Generate a unique container name and ensure cleanup on test exit."""
+    safe = request.node.name.replace("[", "_").replace("]", "_")
+    name = f"hermes-test-{safe}"
+    yield name
+    subprocess.run(
+        ["docker", "rm", "-f", name],
+        capture_output=True, timeout=10,
+    )
+
+
+# ---------------------------------------------------------------------------
+# docker_exec — default to the unprivileged hermes user
+# ---------------------------------------------------------------------------
+#
+# Background: every Hermes runtime path inside the container drops to UID
+# 10000 (the ``hermes`` user) via ``s6-setuidgid hermes``. ``docker exec``
+# without ``-u`` runs as root, which is **not** representative of how
+# production code executes. PR #30136 review caught a real regression
+# this way — ``Path('/proc/1/exe').resolve()`` works as root and silently
+# fails (PermissionError swallowed) for hermes, so a test that ran as root
+# couldn't catch a feature that was inert for the actual runtime user.
+#
+# Tests in this directory MUST exercise the realistic user context. The
+# helpers below run every probe under ``-u hermes`` unless a specific
+# test explicitly opts into ``user="root"`` (rare — e.g. inspecting
+# /proc/1/exe itself, chowning a volume).
+# ---------------------------------------------------------------------------
+
+
+def docker_exec(
+    container: str,
+    *args: str,
+    user: str = "hermes",
+    timeout: int = 30,
+    extra_docker_args: tuple[str, ...] = (),
+) -> subprocess.CompletedProcess[str]:
+    """Run a command inside ``container`` as ``user`` (default: hermes).
+
+    Returns the CompletedProcess with text=True, capture_output=True.
+
+    Pass ``user="root"`` only when the test specifically needs root
+    capabilities (e.g. reading /proc/1/exe, manipulating ownership).
+    Most tests should use the default.
+    """
+    cmd = ["docker", "exec", "-u", user, *extra_docker_args, container, *args]
+    return subprocess.run(
+        cmd, capture_output=True, text=True, timeout=timeout,
+    )
+
+
+def docker_exec_sh(
+    container: str,
+    command: str,
+    *,
+    user: str = "hermes",
+    timeout: int = 30,
+) -> subprocess.CompletedProcess[str]:
+    """Run ``sh -c <command>`` inside the container as ``user``."""
+    return docker_exec(
+        container, "sh", "-c", command, user=user, timeout=timeout,
+    )

tests/docker/test_container_restart.py

@@ -0,0 +1,328 @@
+"""Container-restart survives per-profile gateway registrations.
+
+The s6 dynamic scandir at /run/service/ lives on tmpfs and is wiped
+on every container restart. Phase 4 Task 4.0's container_boot module
++ cont-init.d/02-reconcile-profiles regenerate the service slots from
+$HERMES_HOME/profiles/<name>/gateway_state.json on every boot and
+auto-start only those whose last state was `running`.
+
+These tests stand up a container with a named volume, create profiles
+inside it in various gateway states, restart the container, and
+assert the reconciler did the right thing.
+
+Every ``docker exec`` here runs as the unprivileged ``hermes`` user
+(via :func:`docker_exec` / :func:`docker_exec_sh` in conftest); see
+the conftest module docstring.
+"""
+from __future__ import annotations
+
+import subprocess
+import time
+
+import pytest
+
+from tests.docker.conftest import docker_exec, docker_exec_sh
+
+
+def _docker(*args: str, **kw) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["docker", *args],
+        capture_output=True, text=True, timeout=kw.pop("timeout", 60),
+        **kw,
+    )
+
+
+def _exec(container: str, *args: str, timeout: int = 30) -> subprocess.CompletedProcess[str]:
+    return docker_exec(container, *args, timeout=timeout)
+
+
+def _sh(container: str, cmd: str, timeout: int = 30) -> subprocess.CompletedProcess[str]:
+    return docker_exec_sh(container, cmd, timeout=timeout)
+
+
+def _wait_for_path(
+    container: str,
+    path: str,
+    *,
+    kind: str = "f",
+    deadline_s: float = 30.0,
+    interval_s: float = 0.25,
+) -> bool:
+    """Poll `test -<kind> <path>` inside container until success or timeout.
+
+    `kind` is the `test` flag: 'f' for file, 'd' for directory, 'e' for
+    existence. Returns True on success, False on timeout. Strictly
+    better than a fixed `time.sleep()` because:
+
+      * we don't wait the full budget when the path appears early, and
+      * the test fails with a precise "waited N seconds" assertion
+        instead of a confusing one-line failure mid-test when the
+        sleep was too short.
+    """
+    end = time.monotonic() + deadline_s
+    while time.monotonic() < end:
+        r = _sh(container, f"test -{kind} {path}", timeout=5)
+        if r.returncode == 0:
+            return True
+        time.sleep(interval_s)
+    return False
+
+
+def _wait_for_reconcile_log_mention(
+    container: str,
+    profile: str,
+    *,
+    deadline_s: float = 30.0,
+    interval_s: float = 0.25,
+) -> str:
+    """Poll until /opt/data/logs/container-boot.log mentions `profile`.
+
+    Returns the matching log content on success. On timeout, returns
+    the last observed contents so the assertion can render a
+    meaningful diagnostic. The container-boot.log is the explicit
+    signal that the reconciler has finished — much more reliable
+    than a fixed sleep that hopes 8 seconds is enough.
+    """
+    end = time.monotonic() + deadline_s
+    last = ""
+    while time.monotonic() < end:
+        r = _sh(container, "cat /opt/data/logs/container-boot.log", timeout=5)
+        if r.returncode == 0:
+            last = r.stdout
+            if f"profile={profile}" in last:
+                return last
+        time.sleep(interval_s)
+    return last
+
+
+@pytest.fixture
+def restart_container(request, built_image: str):
+    """A long-running container with a named volume so docker restart
+    preserves $HERMES_HOME/profiles/."""
+    safe = request.node.name.replace("[", "_").replace("]", "_")
+    name = f"hermes-restart-{safe}"
+    volume = f"hermes-restart-vol-{safe}"
+    _docker("rm", "-f", name)
+    _docker("volume", "rm", "-f", volume)
+    _docker("volume", "create", volume, timeout=10).check_returncode()
+    r = _docker(
+        "run", "-d", "--name", name,
+        "-v", f"{volume}:/opt/data",
+        built_image, "sleep", "infinity",
+        timeout=30,
+    )
+    r.check_returncode()
+    # Wait for s6 + stage2 + 02-reconcile to publish the boot log so
+    # the test can rely on the default slot being registered before
+    # it starts issuing commands. The reconciler always writes one
+    # 'default' line on every boot (PR #30136 item I1) — that's our
+    # readiness signal.
+    deadline = time.monotonic() + 30.0
+    while time.monotonic() < deadline:
+        r = _docker(
+            "exec", "-u", "hermes", name, "sh", "-c",
+            "cat /opt/data/logs/container-boot.log 2>/dev/null",
+            timeout=5,
+        )
+        if r.returncode == 0 and "profile=default" in r.stdout:
+            break
+        time.sleep(0.25)
+    else:
+        # Defensive: surface a timeout from the fixture itself so the
+        # test failure points at "container never finished cont-init"
+        # rather than mid-test where the symptom would be obscure.
+        raise RuntimeError(
+            f"container {name} did not finish cont-init within 30s"
+        )
+    yield name
+    _docker("rm", "-f", name)
+    _docker("volume", "rm", "-f", volume)
+
+
+def test_running_gateway_survives_container_restart(restart_container: str) -> None:
+    container = restart_container
+
+    # Create the profile + start its gateway. The Phase 4 hooks
+    # register the s6 service slot during create and the dispatch
+    # path brings it up via s6-svc -u.
+    r = _exec(container, "hermes", "profile", "create", "coder")
+    assert r.returncode == 0, f"profile create failed: {r.stderr}"
+
+    r = _exec(container, "hermes", "-p", "coder", "gateway", "start", timeout=60)
+    assert r.returncode == 0, f"gateway start failed: {r.stderr}"
+
+    # Give the service time to actually come up under supervision.
+    deadline = time.monotonic() + 15.0
+    while time.monotonic() < deadline:
+        r = _sh(container, "/command/s6-svstat /run/service/gateway-coder")
+        if r.returncode == 0 and "up " in r.stdout:
+            break
+        time.sleep(0.5)
+    assert "up " in r.stdout, f"gateway never came up pre-restart: {r.stdout!r}"
+
+    # Persist state so the reconciler will treat the slot as 'running'
+    # post-restart. The gateway process itself writes gateway_state.json
+    # via gateway/status.py — but we don't want to wait for or assert
+    # against the live process here; just stamp the file directly to
+    # exercise the reconciler's contract.
+    write_state = (
+        "import json, pathlib; "
+        "p = pathlib.Path('/opt/data/profiles/coder/gateway_state.json'); "
+        "p.write_text(json.dumps({'gateway_state': 'running', 'timestamp': 1}))"
+    )
+    _exec(container, "python3", "-c", write_state, timeout=10).check_returncode()
+
+    # Restart. After this, /run/service/ is empty until cont-init.d
+    # runs the reconciler. We need to wait long enough for the
+    # reconciler to write coder's entry to the boot log AND for
+    # s6-svscan to spin up the service supervise tree from the
+    # restored slot. Polling the boot log gives us the first signal.
+    _docker("restart", container, timeout=60).check_returncode()
+    log = _wait_for_reconcile_log_mention(container, "coder", deadline_s=30.0)
+    assert "profile=coder" in log, (
+        f"reconciler never logged coder after restart: {log!r}"
+    )
+    assert "action=started" in log
+
+    # Service slot exists.
+    assert _wait_for_path(
+        container, "/run/service/gateway-coder", kind="d", deadline_s=10.0,
+    ), "slot not recreated after restart"
+
+    # No `down` marker — we asked for auto-start.
+    r = _sh(container, "test -f /run/service/gateway-coder/down")
+    assert r.returncode != 0, "down marker present despite prior_state=running"
+
+
+def test_stopped_gateway_stays_stopped_after_restart(restart_container: str) -> None:
+    container = restart_container
+
+    _exec(container, "hermes", "profile", "create", "writer").check_returncode()
+
+    # Write 'stopped' directly so we don't have to race against the
+    # gateway's own state writes.
+    write_state = (
+        "import json, pathlib; "
+        "p = pathlib.Path('/opt/data/profiles/writer/gateway_state.json'); "
+        "p.write_text(json.dumps({'gateway_state': 'stopped', 'timestamp': 1}))"
+    )
+    _exec(container, "python3", "-c", write_state, timeout=10).check_returncode()
+
+    _docker("restart", container, timeout=60).check_returncode()
+    log = _wait_for_reconcile_log_mention(container, "writer", deadline_s=30.0)
+    assert "profile=writer" in log
+
+    # Slot exists.
+    assert _wait_for_path(
+        container, "/run/service/gateway-writer", kind="d", deadline_s=10.0,
+    )
+
+    # Down marker present.
+    r = _sh(container, "test -f /run/service/gateway-writer/down")
+    assert r.returncode == 0, "down marker missing despite prior_state=stopped"
+
+
+def test_stale_gateway_pid_cleaned_up_on_restart(restart_container: str) -> None:
+    """A dead container's gateway.pid + processes.json must NOT
+    survive the restart — a numerically-equal live PID in the new
+    container is a different process and would confuse the gateway
+    process-mismatch checks."""
+    container = restart_container
+
+    _exec(container, "hermes", "profile", "create", "ghost").check_returncode()
+
+    # Stamp stale runtime files alongside a 'running' state so the
+    # reconciler walks this profile.
+    stamp = (
+        "import json, pathlib; "
+        "p = pathlib.Path('/opt/data/profiles/ghost'); "
+        "(p / 'gateway_state.json').write_text(json.dumps({'gateway_state': 'stopped', 'timestamp': 1})); "
+        "(p / 'gateway.pid').write_text(json.dumps({'pid': 99999, 'host': 'old'})); "
+        "(p / 'processes.json').write_text('[]')"
+    )
+    _exec(container, "python3", "-c", stamp, timeout=10).check_returncode()
+
+    _docker("restart", container, timeout=60).check_returncode()
+    _wait_for_reconcile_log_mention(container, "ghost", deadline_s=30.0)
+
+    # Stale runtime files swept.
+    r = _sh(container, "test -f /opt/data/profiles/ghost/gateway.pid")
+    assert r.returncode != 0, "stale gateway.pid survived restart"
+    r = _sh(container, "test -f /opt/data/profiles/ghost/processes.json")
+    assert r.returncode != 0, "stale processes.json survived restart"
+
+
+def test_live_gateway_autostarts_after_real_restart_without_manual_state_stamp(
+    restart_container: str,
+) -> None:
+    """End-to-end guard for issue #42675.
+
+    The other tests in this module stamp gateway_state.json directly to
+    exercise the reconciler's READ side. This one exercises the WRITE
+    side: a real, live gateway is killed by the container/s6 SIGTERM that
+    `docker restart` sends — no manual state stamp — and must come back up
+    on the next boot.
+
+    Before the fix, the shutdown handler unconditionally persisted
+    gateway_state=stopped on that SIGTERM, so the reconciler saw 'stopped'
+    and registered the slot DOWN — the gateway silently stayed dark after
+    every container restart. The fix classifies an unmarked SIGTERM as
+    signal-initiated and persists 'running' instead, so auto-start works.
+    """
+    container = restart_container
+
+    _exec(container, "hermes", "profile", "create", "live").check_returncode()
+    r = _exec(container, "hermes", "-p", "live", "gateway", "start", timeout=60)
+    assert r.returncode == 0, f"gateway start failed: {r.stderr}"
+
+    # Wait for the gateway to actually come up under supervision AND write
+    # its own gateway_state=running (we do NOT stamp it ourselves).
+    deadline = time.monotonic() + 20.0
+    while time.monotonic() < deadline:
+        r = _sh(container, "/command/s6-svstat /run/service/gateway-live")
+        if r.returncode == 0 and "up " in r.stdout:
+            break
+        time.sleep(0.5)
+    assert "up " in r.stdout, f"gateway never came up pre-restart: {r.stdout!r}"
+
+    # Confirm the gateway persisted its own 'running' state (sanity: we're
+    # testing the real write path, not a stamped fixture).
+    deadline = time.monotonic() + 15.0
+    state = ""
+    while time.monotonic() < deadline:
+        r = _sh(
+            container,
+            "cat /opt/data/profiles/live/gateway_state.json 2>/dev/null",
+        )
+        if r.returncode == 0 and '"gateway_state"' in r.stdout:
+            state = r.stdout
+            break
+        time.sleep(0.5)
+    assert '"running"' in state, (
+        f"gateway never persisted running state pre-restart: {state!r}"
+    )
+
+    # Real restart — Docker sends SIGTERM to PID 1; s6 propagates it to the
+    # supervised gateway. No planned-stop marker is written (this is not an
+    # operator `hermes gateway stop`), so the shutdown is signal-initiated.
+    _docker("restart", container, timeout=60).check_returncode()
+
+    log = _wait_for_reconcile_log_mention(container, "live", deadline_s=30.0)
+    assert "profile=live" in log, (
+        f"reconciler never logged live after restart: {log!r}"
+    )
+    # The crux: the reconciler must AUTO-START it, not register it down.
+    assert "action=started" in log, (
+        f"gateway did NOT auto-start after a real restart (issue #42675 "
+        f"regression): {log!r}"
+    )
+
+    # Slot recreated, and NO down marker (we expect auto-start).
+    assert _wait_for_path(
+        container, "/run/service/gateway-live", kind="d", deadline_s=10.0,
+    ), "slot not recreated after restart"
+    r = _sh(container, "test -f /run/service/gateway-live/down")
+    assert r.returncode != 0, (
+        "down marker present despite a live gateway being restarted — "
+        "the signal-initiated shutdown wrongly persisted 'stopped' (#42675)"
+    )

tests/docker/test_dashboard.py

@@ -0,0 +1,415 @@
+"""Harness: dashboard opt-in via HERMES_DASHBOARD.
+
+Today (tini): dashboard starts once when HERMES_DASHBOARD=1; if it crashes
+it stays dead. After Phase 2 (s6): dashboard starts once; if it crashes
+it is restarted under supervision. The restart-after-crash test lives in
+Phase 2 Task 2.5; this file only locks the opt-in surface (which must
+not change between tini and s6).
+
+Every ``docker exec`` here runs as the unprivileged ``hermes`` user
+(via :func:`docker_exec`/:func:`docker_exec_sh` in conftest), matching
+the realistic runtime context. See the conftest module docstring.
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+import time
+
+from tests.docker.conftest import docker_exec, docker_exec_sh
+
+
+def _poll(container: str, probe: str, *, deadline_s: float = 30.0,
+          interval_s: float = 0.5) -> tuple[bool, str]:
+    """Repeatedly run ``probe`` inside the container until it exits 0 or
+    ``deadline_s`` elapses. Returns (success, last stdout)."""
+    end = time.monotonic() + deadline_s
+    last = ""
+    while time.monotonic() < end:
+        r = docker_exec_sh(container, probe, timeout=10)
+        last = r.stdout
+        if r.returncode == 0:
+            return True, last
+        time.sleep(interval_s)
+    return False, last
+
+
+def test_dashboard_not_running_by_default(
+    built_image: str, container_name: str,
+) -> None:
+    """Without HERMES_DASHBOARD, no dashboard process should be running."""
+    subprocess.run(
+        ["docker", "run", "-d", "--name", container_name, built_image,
+         "sleep", "60"],
+        check=True, capture_output=True, timeout=30,
+    )
+    # Give the entrypoint enough time to finish bootstrap; if a dashboard
+    # were going to start it'd be visible by now.
+    time.sleep(5)
+    r = docker_exec(container_name, "pgrep", "-f", "hermes dashboard")
+    # pgrep exits non-zero when no match found
+    assert r.returncode != 0, (
+        "Dashboard should not be running without HERMES_DASHBOARD"
+    )
+
+
+def test_dashboard_slot_reports_down_when_disabled(
+    built_image: str, container_name: str,
+) -> None:
+    """Without HERMES_DASHBOARD, s6-svstat should report the dashboard
+    slot as DOWN (not up-with-sleep-infinity, which would
+    false-positive `hermes doctor` and any other health check).
+
+    Locks the PR #30136 review item I3 fix: cont-init.d/03-dashboard-toggle
+    writes a `down` marker file in the live service-dir when
+    HERMES_DASHBOARD is unset, so the slot reflects reality.
+    """
+    subprocess.run(
+        ["docker", "run", "-d", "--name", container_name, built_image,
+         "sleep", "60"],
+        check=True, capture_output=True, timeout=30,
+    )
+    time.sleep(5)
+    # /command/ isn't on PATH for docker-exec sessions, so call by
+    # absolute path.
+    r = docker_exec(
+        container_name, "/command/s6-svstat", "/run/service/dashboard",
+    )
+    assert r.returncode == 0, f"s6-svstat failed: {r.stderr!r} / {r.stdout!r}"
+    assert "down" in r.stdout, (
+        f"Dashboard slot should be 'down' without HERMES_DASHBOARD; "
+        f"svstat reports: {r.stdout!r}"
+    )
+
+
+def test_dashboard_slot_reports_up_when_enabled(
+    built_image: str, container_name: str,
+) -> None:
+    """Symmetry: with HERMES_DASHBOARD=1, s6-svstat reports the slot as up."""
+    subprocess.run(
+        ["docker", "run", "-d", "--name", container_name,
+         "-e", "HERMES_DASHBOARD=1",
+         # The default dashboard host is 0.0.0.0, which now engages the
+         # OAuth auth gate. Without a provider registered (no
+         # HERMES_DASHBOARD_OAUTH_CLIENT_ID in this test env), start_server
+         # would fail closed and the slot would never come up. Pin the
+         # explicit insecure opt-in to keep this test focused on the s6
+         # supervision contract, not the auth gate.
+         "-e", "HERMES_DASHBOARD_INSECURE=1",
+         built_image, "sleep", "120"],
+        check=True, capture_output=True, timeout=30,
+    )
+    # uvicorn takes a moment to bind; poll svstat.
+    deadline = time.monotonic() + 30.0
+    last = ""
+    while time.monotonic() < deadline:
+        r = docker_exec(
+            container_name, "/command/s6-svstat", "/run/service/dashboard",
+        )
+        last = r.stdout
+        if r.returncode == 0 and "up " in r.stdout:
+            return  # success
+        time.sleep(0.5)
+    raise AssertionError(
+        f"Dashboard slot never reached up state; last svstat: {last!r}"
+    )
+
+
+def test_dashboard_opt_in_starts(
+    built_image: str, container_name: str,
+) -> None:
+    """With HERMES_DASHBOARD=1, a dashboard process should be visible."""
+    subprocess.run(
+        ["docker", "run", "-d", "--name", container_name,
+         "-e", "HERMES_DASHBOARD=1",
+         # Default bind is 0.0.0.0; pin insecure opt-in so the auth gate
+         # doesn't fail-closed before the process can come up. See
+         # test_dashboard_slot_reports_up_when_enabled for the full rationale.
+         "-e", "HERMES_DASHBOARD_INSECURE=1",
+         built_image, "sleep", "120"],
+        check=True, capture_output=True, timeout=30,
+    )
+    # Poll for the dashboard subprocess to appear — the entrypoint
+    # backgrounds it and bootstrap (skills sync etc.) can take a few
+    # seconds before the python process actually launches.
+    ok, _ = _poll(
+        container_name, "pgrep -f 'hermes dashboard'", deadline_s=30.0,
+    )
+    assert ok, "Dashboard should be running with HERMES_DASHBOARD=1"
+
+
+def test_dashboard_port_override(
+    built_image: str, container_name: str,
+) -> None:
+    """HERMES_DASHBOARD_PORT changes the dashboard's listen port."""
+    subprocess.run(
+        ["docker", "run", "-d", "--name", container_name,
+         "-e", "HERMES_DASHBOARD=1", "-e", "HERMES_DASHBOARD_PORT=9120",
+         # Default bind is 0.0.0.0; pin insecure opt-in so the auth gate
+         # doesn't fail-closed before the port is bound. See
+         # test_dashboard_slot_reports_up_when_enabled for the full rationale.
+         "-e", "HERMES_DASHBOARD_INSECURE=1",
+         built_image, "sleep", "120"],
+        check=True, capture_output=True, timeout=30,
+    )
+    # The dashboard process appearing in pgrep doesn't mean it's bound
+    # to the port yet — uvicorn takes another second or two to come up.
+    # The image doesn't ship ss/netstat, so probe /proc/net/tcp directly:
+    # port 9120 = 0x23A0, state 0A = LISTEN.
+    ok, stdout = _poll(
+        container_name,
+        "grep -E ' 0+:23A0 .* 0A ' /proc/net/tcp /proc/net/tcp6 "
+        "2>/dev/null",
+        deadline_s=60.0,
+    )
+    assert ok, f"Dashboard not listening on port 9120: stdout={stdout!r}"
+
+
+def test_dashboard_restarts_after_crash(
+    built_image: str, container_name: str,
+) -> None:
+    """Phase 2 invariant: under s6 supervision, killing the dashboard
+    process should be recovered automatically.
+
+    Pre-s6 (tini) behavior was "stays dead" — the test wouldn't have
+    passed against that image. After the s6-overlay migration the
+    dashboard runs as a longrun s6-rc service and s6-supervise restarts
+    it after a ~1s backoff (the default).
+    """
+    subprocess.run(
+        ["docker", "run", "-d", "--name", container_name,
+         "-e", "HERMES_DASHBOARD=1",
+         # Default bind is 0.0.0.0; pin insecure opt-in so the auth gate
+         # doesn't fail-closed before the supervised dashboard can come up.
+         # See test_dashboard_slot_reports_up_when_enabled for the full
+         # rationale.
+         "-e", "HERMES_DASHBOARD_INSECURE=1",
+         built_image, "sleep", "120"],
+        check=True, capture_output=True, timeout=30,
+    )
+    # Wait for the first dashboard to come up.
+    ok, _ = _poll(
+        container_name, "pgrep -f 'hermes dashboard'", deadline_s=30.0,
+    )
+    assert ok, "Dashboard never started initially"
+
+    # Grab the initial PID. s6 may briefly transition through restart
+    # state between our poll-success and the follow-up pgrep, so retry
+    # a couple of times before giving up.
+    first_pid: str | None = None
+    for _attempt in range(10):
+        first_pid_result = docker_exec(
+            container_name, "pgrep", "-f", "hermes dashboard",
+        )
+        first_pids = first_pid_result.stdout.strip().split()
+        if first_pids:
+            first_pid = first_pids[0]
+            break
+        time.sleep(0.5)
+    assert first_pid is not None, "Could not capture initial dashboard PID"
+
+    # Kill the dashboard. The dashboard process runs as hermes, so the
+    # hermes user can kill it (same UID).
+    docker_exec(container_name, "kill", "-9", first_pid)
+
+    # s6 backs off ~1s before restart; allow up to 15s for the new
+    # process to appear with a different PID.
+    deadline = time.monotonic() + 15.0
+    while time.monotonic() < deadline:
+        r = docker_exec(container_name, "pgrep", "-f", "hermes dashboard")
+        pids = r.stdout.strip().split() if r.returncode == 0 else []
+        if pids and pids[0] != first_pid:
+            return  # success
+        time.sleep(0.5)
+
+    raise AssertionError(
+        f"Dashboard not restarted after kill (first_pid={first_pid})"
+    )
+
+
+# ---------------------------------------------------------------------------
+# OAuth auth-gate behaviour — regression guard for the dashboard-insecure
+# auto-injection bug. Pre-fix, the s6 run script appended `--insecure`
+# whenever `HERMES_DASHBOARD_HOST` was non-loopback, silently disabling
+# the OAuth gate on every container-deployed dashboard. The matching
+# static-text guard lives in tests/test_docker_home_override_scripts.py;
+# this is the behavioural end-to-end check.
+# ---------------------------------------------------------------------------
+
+
+def _http_probe(
+    container: str,
+    path: str,
+    *,
+    deadline_s: float = 60.0,
+) -> tuple[int, str]:
+    """Poll ``http://127.0.0.1:9119<path>`` from inside the container.
+
+    Returns ``(status_code, body)`` as soon as the dashboard answers any
+    HTTP response — 200, 401, 503, anything. The image doesn't ship
+    ``curl`` but the venv's stdlib ``urllib`` is good enough; we use a
+    proper ``try``/``except`` to intercept ``HTTPError`` because
+    ``urlopen`` raises on 4xx/5xx, and we treat those as legitimate
+    responses (the OAuth gate's 401 IS the success signal for the
+    gate-engaged test).
+
+    Connection errors (uvicorn still starting, fail-closed exited) keep
+    the poll loop running until ``deadline_s`` elapses.
+
+    The probe Python program is fed over stdin (``python -``) rather
+    than ``python -c`` so we can use proper multi-line syntax with
+    ``try``/``except`` blocks without escaping hell.
+
+    Raises ``AssertionError`` on timeout.
+    """
+    py_program = f"""\
+import urllib.request, urllib.error
+req = urllib.request.Request("http://127.0.0.1:9119{path}")
+try:
+    r = urllib.request.urlopen(req, timeout=5)
+    print(r.status)
+    print(r.read().decode(), end="")
+except urllib.error.HTTPError as h:
+    print(h.code)
+    print(h.read().decode(), end="")
+"""
+    # Feed the program over stdin via a heredoc so docker_exec_sh's
+    # single bash string stays clean. The 'PY' delimiter is quoted to
+    # disable shell expansion inside the heredoc body.
+    probe = (
+        "/opt/hermes/.venv/bin/python - <<'PY'\n"
+        f"{py_program}"
+        "PY"
+    )
+    end = time.monotonic() + deadline_s
+    last_err = ""
+    while time.monotonic() < end:
+        r = docker_exec_sh(container, probe, timeout=10)
+        if r.returncode == 0 and r.stdout.strip():
+            lines = r.stdout.split("\n", 1)
+            try:
+                status = int(lines[0].strip())
+                body = lines[1] if len(lines) > 1 else ""
+                return status, body
+            except (ValueError, IndexError) as exc:
+                last_err = f"parse: {exc!r} / stdout={r.stdout!r}"
+        else:
+            last_err = f"rc={r.returncode} stderr={r.stderr!r}"
+        time.sleep(0.5)
+    raise AssertionError(
+        f"Probe of {path} never returned HTTP within {deadline_s}s; "
+        f"last error: {last_err}"
+    )
+
+
+def test_dashboard_oauth_gate_engages_on_non_loopback_bind(
+    built_image: str, container_name: str,
+) -> None:
+    """The s6 dashboard run script must NOT auto-add ``--insecure`` when the
+    dashboard binds to ``0.0.0.0``. The OAuth auth gate engages on its own
+    when a ``DashboardAuthProvider`` is registered (the bundled nous
+    provider activates whenever ``HERMES_DASHBOARD_OAUTH_CLIENT_ID`` is
+    set).
+
+    Regression guard for the wildcard-subdomain rollout where every
+    portal-provisioned agent binds ``0.0.0.0`` and relies on the OAuth
+    gate to authenticate browser callers. Before this fix, the run script
+    flipped ``--insecure`` on for any non-loopback bind, which routed
+    ``start_server`` straight back into the legacy ``allow_public=True``
+    branch and disabled the gate every time.
+
+    We verify two independent observable consequences of the gate being
+    on:
+
+    1. ``/api/auth/providers`` (publicly reachable through the gate so
+       the login page can bootstrap) returns 200 with ``nous`` in the
+       provider list — proves the bundled provider registered.
+    2. ``/api/sessions`` (a gated route under both the legacy
+       ``_SESSION_TOKEN`` middleware and the OAuth gate) returns 401
+       to an unauthenticated caller — proves the OAuth gate is actively
+       intercepting browser traffic. We deliberately probe a gated route
+       here rather than ``/api/status``: status sits in the shared
+       ``PUBLIC_API_PATHS`` allowlist (portal liveness probe target) and
+       responds 200 without a cookie under both gates, so it cannot
+       distinguish "gate on" from "gate off".
+    """
+    subprocess.run(
+        ["docker", "run", "-d", "--name", container_name,
+         "-e", "HERMES_DASHBOARD=1",
+         "-e", "HERMES_DASHBOARD_HOST=0.0.0.0",
+         "-e", "HERMES_DASHBOARD_OAUTH_CLIENT_ID=agent:test-instance",
+         built_image, "sleep", "120"],
+        check=True, capture_output=True, timeout=30,
+    )
+
+    # (1) Provider registry visible via the public bootstrap endpoint.
+    status_code, body = _http_probe(container_name, "/api/auth/providers")
+    assert status_code == 200, (
+        f"/api/auth/providers should return 200 when a provider is "
+        f"registered; got {status_code} body={body!r}"
+    )
+    payload = json.loads(body)
+    provider_names = [p.get("name") for p in payload.get("providers", [])]
+    assert "nous" in provider_names, (
+        "Bundled dashboard_auth/nous provider should register when "
+        f"HERMES_DASHBOARD_OAUTH_CLIENT_ID is set. Got: {payload!r}"
+    )
+
+    # (2) A gated route (``/api/sessions``) returns 401 to an
+    #     unauthenticated caller — the OAuth gate is intercepting.
+    status_code, body = _http_probe(container_name, "/api/sessions")
+    assert status_code == 401, (
+        "OAuth gate must intercept gated /api/* routes on 0.0.0.0 bind "
+        "when a provider is registered and HERMES_DASHBOARD_INSECURE "
+        f"is unset. Got: status={status_code} body={body!r}"
+    )
+
+    # (3) ``/api/status`` remains 200 under the gate — it's in the shared
+    #     ``PUBLIC_API_PATHS`` allowlist so NAS's wildcard-subdomain
+    #     liveness probe (``fly-provider.ts`` ``getInstanceRuntimeStatus``)
+    #     can reach it without a cookie. Regression guard: this allowlist
+    #     drifted once already and surfaced every healthy agent as
+    #     STARTING/down in the portal UI.
+    status_code, body = _http_probe(container_name, "/api/status")
+    assert status_code == 200, (
+        "/api/status must remain publicly reachable under the OAuth gate "
+        "— the portal uses it as the wildcard-subdomain liveness probe. "
+        f"Got: status={status_code} body={body!r}"
+    )
+    status = json.loads(body)
+    assert status.get("auth_required") is True, (
+        "/api/status must report auth_required=True when the OAuth gate "
+        f"is engaged so the SPA/portal can distinguish modes. Got: {status!r}"
+    )
+
+
+def test_dashboard_insecure_env_var_opts_out_of_gate(
+    built_image: str, container_name: str,
+) -> None:
+    """``HERMES_DASHBOARD_INSECURE=1`` re-enables the legacy no-gate mode
+    for operators running on trusted LANs behind a reverse proxy without
+    the OAuth contract. Same opt-out shape as the rest of the s6 boolean
+    envs (e.g. ``HERMES_DASHBOARD``).
+
+    With the gate off, ``/api/status`` (a public endpoint under the
+    legacy ``_SESSION_TOKEN`` middleware) returns 200 with the
+    ``auth_required: false`` body — proves the gate is bypassed.
+    """
+    subprocess.run(
+        ["docker", "run", "-d", "--name", container_name,
+         "-e", "HERMES_DASHBOARD=1",
+         "-e", "HERMES_DASHBOARD_HOST=0.0.0.0",
+         "-e", "HERMES_DASHBOARD_INSECURE=1",
+         built_image, "sleep", "120"],
+        check=True, capture_output=True, timeout=30,
+    )
+    status_code, body = _http_probe(container_name, "/api/status")
+    assert status_code == 200, (
+        f"/api/status should return 200 with the auth gate disabled; "
+        f"got {status_code} body={body!r}"
+    )
+    status = json.loads(body)
+    assert status.get("auth_required") is False, (
+        "HERMES_DASHBOARD_INSECURE=1 must disable the auth gate (explicit "
+        f"opt-in for trusted-LAN deployments). Got: {status!r}"
+    )

tests/docker/test_docker_exec_privilege_drop.py

@@ -0,0 +1,290 @@
+"""Regression tests for the docker-exec privilege-drop shim.
+
+The shim (docker/hermes-exec-shim.sh, installed at /opt/hermes/bin/hermes)
+exists to prevent the auth.json ownership-mismatch bug where
+`docker exec <c> hermes login` would write /opt/data/auth.json as
+root:root mode 0600, leaving the supervised gateway (UID 10000) unable
+to read its own credentials and returning "Provider authentication
+failed: Hermes is not logged into Nous Portal" on every message.
+
+These tests verify:
+
+1. ``docker exec <c> hermes …`` (defaulting to root) gets dropped to the
+   hermes user before the real binary runs.
+2. ``docker exec --user hermes <c> hermes …`` (already non-root) short-
+   circuits and doesn't try to drop again.
+3. Files written under $HERMES_HOME from a ``docker exec`` session land
+   as hermes:hermes — the actual user-visible invariant.
+4. The HERMES_DOCKER_EXEC_AS_ROOT opt-out lets diagnostic sessions keep
+   running as root deliberately.
+5. The main CMD path (``docker run <image> …``) is unaffected by the
+   PATH-shim ordering — no recursion, no behavior change.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import time
+from collections.abc import Iterator
+
+import pytest
+
+
+# How long to give a `docker run -d` container before declaring it not ready.
+_RUN_READY_TIMEOUT_S = 20
+
+
+def _wait_for_init(container: str) -> None:
+    """Block until /init is up enough that `docker exec` is responsive."""
+    deadline = time.time() + _RUN_READY_TIMEOUT_S
+    while time.time() < deadline:
+        r = subprocess.run(
+            ["docker", "exec", container, "true"],
+            capture_output=True, timeout=5,
+        )
+        if r.returncode == 0:
+            return
+        time.sleep(0.2)
+    pytest.fail(f"container {container} not responsive to docker exec within {_RUN_READY_TIMEOUT_S}s")
+
+
+@pytest.fixture
+def sleep_container(built_image: str, container_name: str) -> Iterator[str]:
+    """Long-lived container running `sleep infinity` so we can docker exec into it."""
+    subprocess.run(
+        ["docker", "rm", "-f", container_name],
+        capture_output=True, check=False,
+    )
+    r = subprocess.run(
+        ["docker", "run", "-d", "--name", container_name, built_image,
+         "sleep", "infinity"],
+        capture_output=True, text=True, timeout=30,
+    )
+    assert r.returncode == 0, f"docker run failed: {r.stderr}"
+    try:
+        _wait_for_init(container_name)
+        yield container_name
+    finally:
+        subprocess.run(
+            ["docker", "rm", "-f", container_name],
+            capture_output=True, check=False,
+        )
+
+
+def test_shim_drops_root_to_hermes_uid(sleep_container: str) -> None:
+    """docker exec defaults to root; the shim should drop to uid 10000.
+
+    We invoke `hermes` with a Python-style `-c` shim equivalent — there's no
+    pure-hermes "print my uid" command, so we use the venv's python directly
+    via the shim's PATH lookup: `python -c 'print(os.getuid())'` is resolved
+    through the venv. But that bypasses the shim. Instead, we exploit the
+    fact that the venv's `hermes` is a console_scripts entry — under the
+    hood it's a tiny Python wrapper. We can't easily inject "print my uid"
+    into it without forking subcommands. Simplest approach: have `hermes`
+    do anything that writes to disk, then check the file's owner.
+
+    Use `hermes config set` which writes config.yaml under HERMES_HOME.
+    The resulting file ownership tells us what UID the shim ended up at.
+    """
+    # Wipe any prior state.
+    subprocess.run(
+        ["docker", "exec", "--user", "root", sleep_container,
+         "rm", "-f", "/opt/data/config.yaml"],
+        capture_output=True, check=False,
+    )
+
+    # Default docker exec (root) — should be dropped by the shim.
+    r = subprocess.run(
+        ["docker", "exec", sleep_container,
+         "hermes", "config", "set", "_test.shim_marker", "1"],
+        capture_output=True, text=True, timeout=30,
+    )
+    assert r.returncode == 0, f"config set failed: stdout={r.stdout!r} stderr={r.stderr!r}"
+
+    # The written file must be owned by hermes, not root.
+    r = subprocess.run(
+        ["docker", "exec", sleep_container,
+         "stat", "-c", "%U:%G", "/opt/data/config.yaml"],
+        capture_output=True, text=True, timeout=10,
+    )
+    assert r.returncode == 0, f"stat failed: {r.stderr}"
+    assert r.stdout.strip() == "hermes:hermes", (
+        f"config.yaml owned by {r.stdout.strip()!r}, expected hermes:hermes. "
+        "The shim did not drop privileges before invoking hermes."
+    )
+
+
+def test_shim_short_circuits_for_non_root_exec(sleep_container: str) -> None:
+    """docker exec --user hermes already runs as 10000; shim should be a no-op.
+
+    Verified indirectly: the command must still succeed end-to-end. If the
+    shim incorrectly tried to drop privileges a second time (e.g. by
+    invoking s6-setuidgid which requires root), it would fail with
+    EPERM. A clean success proves the short-circuit fired.
+    """
+    subprocess.run(
+        ["docker", "exec", "--user", "root", sleep_container,
+         "rm", "-f", "/opt/data/config.yaml"],
+        capture_output=True, check=False,
+    )
+
+    r = subprocess.run(
+        ["docker", "exec", "--user", "hermes", sleep_container,
+         "hermes", "config", "set", "_test.shim_short_circuit", "1"],
+        capture_output=True, text=True, timeout=30,
+    )
+    assert r.returncode == 0, (
+        f"docker exec --user hermes failed: {r.stderr!r} stdout={r.stdout!r}. "
+        "If the shim mis-handled the non-root path, this would fail with EPERM."
+    )
+
+    # File still ends up hermes:hermes — orthogonally confirms uid.
+    r = subprocess.run(
+        ["docker", "exec", sleep_container,
+         "stat", "-c", "%U:%G", "/opt/data/config.yaml"],
+        capture_output=True, text=True, timeout=10,
+    )
+    assert r.stdout.strip() == "hermes:hermes"
+
+
+def test_shim_opt_out_keeps_root(sleep_container: str) -> None:
+    """HERMES_DOCKER_EXEC_AS_ROOT=1 should suppress the privilege drop.
+
+    Reserved for diagnostic sessions where the operator deliberately
+    wants root semantics. Verified by writing a file and checking its
+    owner.
+    """
+    subprocess.run(
+        ["docker", "exec", "--user", "root", sleep_container,
+         "rm", "-f", "/opt/data/config.yaml"],
+        capture_output=True, check=False,
+    )
+
+    r = subprocess.run(
+        ["docker", "exec",
+         "-e", "HERMES_DOCKER_EXEC_AS_ROOT=1",
+         sleep_container,
+         "hermes", "config", "set", "_test.opt_out", "1"],
+        capture_output=True, text=True, timeout=30,
+    )
+    assert r.returncode == 0, f"opt-out invocation failed: {r.stderr}"
+
+    r = subprocess.run(
+        ["docker", "exec", sleep_container,
+         "stat", "-c", "%U:%G", "/opt/data/config.yaml"],
+        capture_output=True, text=True, timeout=10,
+    )
+    assert r.stdout.strip() == "root:root", (
+        f"With HERMES_DOCKER_EXEC_AS_ROOT=1, expected root:root, "
+        f"got {r.stdout.strip()!r}"
+    )
+
+
+@pytest.mark.parametrize("falsy_value", ["0", "false", "no", "", "garbage", "2"])
+def test_shim_opt_out_strict_truthiness(
+    sleep_container: str, falsy_value: str,
+) -> None:
+    """Anything other than 1/true/yes (case-insensitive) does NOT opt out.
+
+    Strict truthiness so a typo (``HERMES_DOCKER_EXEC_AS_ROOT=0``) doesn't
+    silently keep the user as root. Mirrors the policy used by
+    ``HERMES_GATEWAY_NO_SUPERVISE`` in #33583.
+    """
+    subprocess.run(
+        ["docker", "exec", "--user", "root", sleep_container,
+         "rm", "-f", "/opt/data/config.yaml"],
+        capture_output=True, check=False,
+    )
+
+    r = subprocess.run(
+        ["docker", "exec",
+         "-e", f"HERMES_DOCKER_EXEC_AS_ROOT={falsy_value}",
+         sleep_container,
+         "hermes", "config", "set", "_test.falsy", "1"],
+        capture_output=True, text=True, timeout=30,
+    )
+    assert r.returncode == 0, f"falsy value {falsy_value!r} caused failure: {r.stderr}"
+
+    r = subprocess.run(
+        ["docker", "exec", sleep_container,
+         "stat", "-c", "%U:%G", "/opt/data/config.yaml"],
+        capture_output=True, text=True, timeout=10,
+    )
+    assert r.stdout.strip() == "hermes:hermes", (
+        f"falsy opt-out value {falsy_value!r} unexpectedly suppressed the drop; "
+        f"file owner is {r.stdout.strip()!r}, expected hermes:hermes"
+    )
+
+
+def test_main_cmd_path_unaffected(built_image: str) -> None:
+    """The CMD path (docker run <image> <args>) must still work.
+
+    The shim sits at /opt/hermes/bin earliest on PATH; main-wrapper.sh
+    invokes `s6-setuidgid hermes hermes <args>` which resolves `hermes`
+    through PATH. With the shim in the way, this could regress if the
+    shim recurses or interferes with TTY/exit-code propagation.
+
+    `chat --help` is cheap and exercises the full subcommand
+    passthrough path. The duplicate of test_main_invocation's
+    pre-existing test is intentional — that one would have passed
+    pre-shim too; this one specifically guards against shim regressions
+    in the CMD-as-main-program codepath.
+    """
+    r = subprocess.run(
+        ["docker", "run", "--rm", built_image, "chat", "--help"],
+        capture_output=True, text=True, timeout=60,
+    )
+    assert r.returncode == 0, f"CMD path broken by shim: stderr={r.stderr!r}"
+    assert "Traceback" not in r.stderr
+
+
+def test_e2e_login_then_supervised_gateway_can_read_auth(
+    sleep_container: str,
+) -> None:
+    """End-to-end regression for the original bug.
+
+    Pre-shim: ``docker exec <c> hermes login`` (root) wrote
+    /opt/data/auth.json as root:root 0600. The supervised gateway (UID
+    10000) couldn't read it, _load_auth_store swallowed PermissionError
+    as a parse failure, and resolve_nous_runtime_credentials raised
+    "Hermes is not logged into Nous Portal" on every message.
+
+    We can't do a real OAuth login in a unit test, but we can stand in
+    for it by writing the same file shape via `hermes config set`-style
+    writes — what matters is the *file ownership invariant* downstream
+    of `_save_auth_store`. If the shim works, every file the
+    `docker exec` path produces is hermes-readable.
+
+    Specifically: pretend the operator ran `hermes login` (writes
+    auth.json) and verify (a) the file exists and (b) it's readable by
+    the hermes UID. We use `hermes auth list` since that touches the
+    auth store on the read side and would fail with the same
+    'not logged in' shape if the file was unreadable to uid 10000.
+    """
+    # Have the shim-protected `docker exec` write the auth store.
+    # `hermes auth list` is read-only but still exercises _load_auth_store
+    # under the shim's UID. We invoke `hermes config set` first to
+    # provoke a write into HERMES_HOME so we have something concrete to
+    # owner-check.
+    r = subprocess.run(
+        ["docker", "exec", sleep_container,
+         "hermes", "config", "set", "_test.e2e_marker", "1"],
+        capture_output=True, text=True, timeout=30,
+    )
+    assert r.returncode == 0, f"config set failed: {r.stderr}"
+
+    # The supervised UID (10000) must be able to read everything under
+    # HERMES_HOME that docker exec just wrote.
+    r = subprocess.run(
+        ["docker", "exec", "--user", "hermes", sleep_container,
+         "find", "/opt/data", "-maxdepth", "2", "-type", "f",
+         "!", "-readable", "-print"],
+        capture_output=True, text=True, timeout=15,
+    )
+    assert r.returncode == 0, f"find failed: {r.stderr}"
+    unreadable = [ln for ln in r.stdout.splitlines() if ln.strip()]
+    assert not unreadable, (
+        "Files written by `docker exec` are unreadable to the hermes user "
+        f"(supervised gateway UID): {unreadable}. The shim failed to drop "
+        "privileges before the write."
+    )

tests/docker/test_dump_build_sha.py

@@ -0,0 +1,104 @@
+"""Regression test: ``hermes dump`` reports a real git SHA inside the container.
+
+Background: ``.dockerignore`` excludes ``.git``, so ``git rev-parse HEAD``
+fails inside the published image and ``hermes dump`` used to report
+``version: ... [(unknown)]``.  The Dockerfile now writes the build-time
+``$HERMES_GIT_SHA`` build-arg to ``/opt/hermes/.hermes_build_sha`` and
+``hermes_cli/build_info.py`` reads it as a fallback.
+
+CI (``.github/workflows/docker-publish.yml``) always sets the build-arg
+to ``${{ github.sha }}``.  Local ``docker build`` (the ``built_image``
+fixture in ``tests/docker/conftest.py``) does NOT — so locally the file
+is absent and ``hermes dump`` correctly falls back to ``(unknown)``.
+
+This test handles both cases:
+
+* If ``/opt/hermes/.hermes_build_sha`` exists in the image, assert that
+  ``hermes dump`` surfaces its content as the version SHA (not
+  ``(unknown)``).
+* If the file is absent, assert the legacy behaviour (``(unknown)``)
+  still holds — defensive guard against the helper accidentally
+  reporting bogus data from somewhere else.
+"""
+from __future__ import annotations
+
+import re
+import subprocess
+
+
+_VERSION_LINE = re.compile(r"^version:\s+(?P<rest>.+)$", re.MULTILINE)
+_SHA_BRACKET = re.compile(r"\[(?P<sha>[^\]]+)\]\s*$")
+
+
+def _run_dump(image: str) -> str:
+    """Return the stdout of ``docker run <image> dump``.
+
+    Relies on Docker's anonymous VOLUME for ``/opt/data`` (declared by the
+    Dockerfile) so the container's hermes user (UID 10000) can bootstrap
+    its config.  Anonymous volumes are auto-cleaned by ``--rm``, so unlike
+    a host bind-mount we don't have to chown anything to UID 10000 (which
+    would break cleanup on non-root hosts).
+    """
+    r = subprocess.run(
+        ["docker", "run", "--rm", image, "dump"],
+        capture_output=True, text=True, timeout=120,
+    )
+    assert r.returncode == 0, (
+        f"hermes dump exited {r.returncode}: "
+        f"stderr={r.stderr[-1000:]!r}\nstdout={r.stdout[-1000:]!r}"
+    )
+    return r.stdout
+
+
+def _read_baked_sha_from_image(image: str) -> str | None:
+    """Return the ``/opt/hermes/.hermes_build_sha`` content, or None if absent."""
+    r = subprocess.run(
+        [
+            "docker", "run", "--rm", "--entrypoint", "cat", image,
+            "/opt/hermes/.hermes_build_sha",
+        ],
+        capture_output=True, text=True, timeout=30,
+    )
+    if r.returncode != 0:
+        return None
+    return r.stdout.strip() or None
+
+
+def test_dump_reports_baked_sha_when_present(built_image: str) -> None:
+    """When the image was built with ``HERMES_GIT_SHA``, dump must surface it.
+
+    Together with the smoke-test action (which exercises ``--help``), this
+    closes the regression loop for the missing-sha bug: any future change
+    that breaks the baked-file -> dump pipeline will fail CI here.
+    """
+    baked = _read_baked_sha_from_image(built_image)
+    stdout = _run_dump(built_image)
+
+    match = _VERSION_LINE.search(stdout)
+    assert match, f"no `version:` line in dump output:\n{stdout[:2000]}"
+    sha_match = _SHA_BRACKET.search(match.group("rest"))
+    assert sha_match, (
+        f"`version:` line missing [<sha>] bracket: {match.group('rest')!r}"
+    )
+    reported = sha_match.group("sha")
+
+    if baked is None:
+        # Local-build path: no build-arg was passed.  Verify the legacy
+        # fallback ``(unknown)`` is intact — guards against the helper
+        # ever inventing a SHA from thin air.
+        assert reported == "(unknown)", (
+            f"expected '(unknown)' when no SHA baked, got {reported!r}"
+        )
+        return
+
+    # CI path: build-arg was set, baked file exists.  ``hermes dump``
+    # truncates to 8 chars via ``git rev-parse --short=8`` semantics.
+    assert reported != "(unknown)", (
+        "baked SHA file present in image but dump still reported "
+        f"'(unknown)' — the build-info fallback is broken.  "
+        f"Baked file content: {baked!r}"
+    )
+    assert reported == baked[:8], (
+        f"dump reported {reported!r} but baked file contained {baked!r} "
+        f"(expected first 8 chars: {baked[:8]!r})"
+    )

tests/docker/test_gateway_run_supervised.py

@@ -0,0 +1,395 @@
+"""Harness: `docker run <image> gateway run` redirects to supervised mode.
+
+Before the s6 migration, ``docker run nousresearch/hermes-agent gateway
+run`` was the standard pattern — the gateway ran as the container's
+main process, container exit code matched gateway exit code, no
+supervision. With s6 as PID 1, the same invocation now auto-redirects
+to the supervised path (`gateway start`) so users get auto-restart on
+crash and a supervised dashboard alongside (when ``HERMES_DASHBOARD=1``).
+
+These tests verify the three load-bearing properties of that redirect:
+
+  1. The default invocation **does** redirect (container stays up via
+     ``sleep infinity`` while s6 supervises ``gateway-default``).
+  2. ``--no-supervise`` / ``HERMES_GATEWAY_NO_SUPERVISE=1`` opts out.
+  3. The supervised process itself does NOT recurse — the
+     ``HERMES_S6_SUPERVISED_CHILD`` sentinel breaks the loop.
+
+Every ``docker exec`` runs as ``hermes`` per the conftest module
+docstring; see ``tests/docker/conftest.py`` for rationale.
+"""
+from __future__ import annotations
+
+import subprocess
+import time
+
+from tests.docker.conftest import docker_exec_sh
+
+
+def _sh(container: str, command: str, timeout: int = 30):
+    return docker_exec_sh(container, command, timeout=timeout)
+
+
+def _svstat(container: str, slot: str = "gateway-default") -> str:
+    r = _sh(container, f"/command/s6-svstat /run/service/{slot}")
+    return r.stdout if r.returncode == 0 else ""
+
+
+def _svstat_wants_up(container: str, slot: str = "gateway-default") -> bool:
+    """See test_profile_gateway._svstat_wants_up for the format rules."""
+    state = _svstat(container, slot)
+    if not state:
+        return False
+    head = state.split()[0] if state.split() else ""
+    if head == "up":
+        return "want down" not in state
+    return "want up" in state
+
+
+def test_gateway_run_redirects_to_supervised(
+    built_image: str, container_name: str,
+) -> None:
+    """``docker run <image> gateway run`` (the historical invocation)
+    should now register and start the ``gateway-default`` s6 slot.
+
+    The CMD process itself shouldn't be the gateway — it should be
+    blocked on ``sleep infinity``, leaving s6 to supervise the actual
+    gateway process. We verify by:
+
+      * Confirming the CMD process is sleeping (not python/gateway).
+      * Confirming ``s6-svstat gateway-default`` reports want-up.
+    """
+    # Start the container detached using the historical gateway-run
+    # pattern. The redirect should fire and the container should NOT
+    # exit immediately (which is what would happen pre-this-PR on the
+    # s6 image — the foreground gateway would crash without config,
+    # the CMD would exit, /init would shut down).
+    subprocess.run(
+        ["docker", "run", "-d", "--name", container_name, built_image,
+         "gateway", "run"],
+        check=True, capture_output=True, timeout=30,
+    )
+
+    # Give /init time to run cont-init.d, the wrapper time to dispatch
+    # the redirect, and s6-supervise time to spin up the slot.
+    time.sleep(5)
+
+    # Container should still be running. If the redirect didn't fire,
+    # the foreground gateway would have crashed and the container
+    # would be in `Exited` state by now.
+    r = subprocess.run(
+        ["docker", "inspect", "-f", "{{.State.Status}}", container_name],
+        capture_output=True, text=True, timeout=10,
+    )
+    assert r.returncode == 0 and r.stdout.strip() == "running", (
+        f"container exited prematurely: {r.stdout!r}; "
+        f"docker logs:\n{subprocess.run(['docker', 'logs', container_name], capture_output=True, text=True).stdout}"
+    )
+
+    # s6's intent for the default-profile gateway slot should be up.
+    # Same accept-either rule as test_profile_gateway: the supervised
+    # gateway may or may not be currently up depending on whether the
+    # harness profile has a configured model, but the want-intent
+    # contract holds either way.
+    assert _svstat_wants_up(container_name), (
+        f"gateway-default slot want-state not up: {_svstat(container_name)!r}"
+    )
+
+    # The CMD process (PID under /init that the wrapper exec'd into)
+    # should be sleeping, not the gateway. We grep `ps` for the
+    # `sleep infinity` heartbeat.
+    r = _sh(container_name, "ps -eo pid,cmd | grep -v grep | grep 'sleep infinity'")
+    assert r.returncode == 0 and "sleep infinity" in r.stdout, (
+        f"expected `sleep infinity` heartbeat process; got ps:\n{r.stdout}\n"
+        f"stderr: {r.stderr}"
+    )
+
+    # And the loud breadcrumb should be in `docker logs` so users see
+    # the upgrade explanation.
+    r = subprocess.run(
+        ["docker", "logs", container_name],
+        capture_output=True, text=True, timeout=10,
+    )
+    logs = r.stdout + r.stderr
+    assert "s6 supervision" in logs, (
+        f"expected loud breadcrumb in docker logs; got:\n{logs}"
+    )
+    assert "--no-supervise" in logs, (
+        f"breadcrumb missing opt-out hint; got:\n{logs}"
+    )
+
+
+def test_gateway_run_no_supervise_flag_preserves_legacy_behavior(
+    built_image: str, container_name: str,
+) -> None:
+    """``docker run <image> gateway run --no-supervise`` opts out of
+    the redirect and runs the gateway as the foreground CMD process
+    (pre-s6 semantics).
+
+    With the redirect in place, the container's CMD process would be
+    ``sleep infinity`` and the supervised gateway would be a separate
+    process under ``s6-supervise gateway-default``. WITHOUT the
+    redirect (opt-out path), there's no supervised gateway slot at
+    all — the gateway IS the CMD process.
+
+    Three positive assertions confirm we took the pre-s6 path:
+
+      * The CMD process is a python ``hermes gateway run`` invocation
+        (not ``sleep infinity``).
+      * The ``gateway-default`` s6 service slot is NOT created.
+      * No supervision-redirect breadcrumb appears in docker logs.
+    """
+    subprocess.run(
+        ["docker", "run", "-d", "--name", container_name, built_image,
+         "gateway", "run", "--no-supervise"],
+        check=True, capture_output=True, timeout=30,
+    )
+    # Give startup time. The unconfigured-profile case used to fail
+    # fast; with a config bind-mounted profile (and a real volume on
+    # most realistic deployments) the gateway just runs.
+    time.sleep(6)
+
+    # Container should still be running OR have exited cleanly with
+    # the gateway's status code. Either is correct for pre-s6
+    # semantics — what's NOT correct is the supervised behavior
+    # (sleep infinity heartbeat + supervised gateway slot).
+    inspect = subprocess.run(
+        ["docker", "inspect", "-f", "{{.State.Status}}", container_name],
+        capture_output=True, text=True, timeout=10,
+    )
+    status = inspect.stdout.strip()
+
+    # No redirect breadcrumb anywhere.
+    logs = subprocess.run(
+        ["docker", "logs", container_name],
+        capture_output=True, text=True, timeout=10,
+    ).stdout + subprocess.run(
+        ["docker", "logs", container_name],
+        capture_output=True, text=True, timeout=10,
+    ).stderr
+    assert "s6 supervision" not in logs, (
+        f"--no-supervise should have skipped the redirect; "
+        f"breadcrumb in logs:\n{logs}"
+    )
+
+    if status == "running":
+        # Gateway running in foreground — the CMD process should be
+        # the gateway itself, NOT a sleep-infinity heartbeat.
+        r = _sh(
+            container_name,
+            "ps -eo pid,ppid,cmd | grep -v grep | awk '/main-wrapper.sh|rc.init top/ { wrapper_pid=$1 } "
+            "$3==\"sleep\" && $4==\"infinity\" && $2==wrapper_pid { c++ } END { print c+0 }'",
+        )
+        assert r.returncode == 0
+        redirected_sleeps = int(r.stdout.strip() or 0)
+        assert redirected_sleeps == 0, (
+            f"--no-supervise: expected NO `sleep infinity` parented to "
+            f"the CMD wrapper (foreground gateway should be the CMD), "
+            f"found {redirected_sleeps}. "
+            f"ps:\n{_sh(container_name, 'ps -eo pid,ppid,cmd').stdout}"
+        )
+
+        # The gateway-default s6 slot exists (the cont-init.d
+        # reconciler creates it on every boot regardless of opt-out)
+        # but should NOT have its want-state set to "up" — the
+        # opt-out path doesn't dispatch `start` to s6.
+        assert not _svstat_wants_up(container_name, "gateway-default"), (
+            "--no-supervise: gateway-default slot has want-state up, "
+            "implying the redirect dispatched `start` despite the "
+            f"opt-out. svstat:\n{_svstat(container_name)!r}"
+        )
+    # If status == "exited" instead, the gateway exited (also valid
+    # pre-s6 semantics). The breadcrumb-absence check above is
+    # already enough to confirm the redirect didn't fire.
+
+
+def test_gateway_run_no_supervise_env_var(
+    built_image: str, container_name: str,
+) -> None:
+    """Env-var opt-out works identically to the CLI flag.
+
+    Useful when users can't easily change their `docker run` args
+    (orchestration templates, K8s manifests) but can set env vars.
+    """
+    subprocess.run(
+        ["docker", "run", "-d", "--name", container_name,
+         "-e", "HERMES_GATEWAY_NO_SUPERVISE=1",
+         built_image, "gateway", "run"],
+        check=True, capture_output=True, timeout=30,
+    )
+    time.sleep(6)
+
+    logs = subprocess.run(
+        ["docker", "logs", container_name],
+        capture_output=True, text=True, timeout=10,
+    )
+    combined = logs.stdout + logs.stderr
+    assert "s6 supervision" not in combined, (
+        f"env-var opt-out should have skipped the redirect; "
+        f"breadcrumb in logs:\n{combined}"
+    )
+
+    # Same as the CLI-flag test: the slot exists (reconciler creates
+    # it) but should not have want-state up.
+    inspect = subprocess.run(
+        ["docker", "inspect", "-f", "{{.State.Status}}", container_name],
+        capture_output=True, text=True, timeout=10,
+    )
+    if inspect.stdout.strip() == "running":
+        assert not _svstat_wants_up(container_name, "gateway-default"), (
+            "HERMES_GATEWAY_NO_SUPERVISE=1: gateway-default has "
+            "want-state up, implying the redirect dispatched `start` "
+            f"despite the env-var opt-out. svstat:\n{_svstat(container_name)!r}"
+        )
+
+
+def test_supervised_gateway_does_not_recurse(
+    built_image: str, container_name: str,
+) -> None:
+    """The HERMES_S6_SUPERVISED_CHILD sentinel must prevent the
+    supervised ``hermes gateway run`` from re-entering the redirect.
+
+    If recursion happened, every supervised gateway start would itself
+    re-dispatch to s6 and exec ``sleep infinity`` — so the supervised
+    gateway slot would never actually run a python ``hermes gateway
+    run`` process. The slot would oscillate or settle into a state
+    with no python in the supervise tree at all.
+
+    We verify by counting python processes whose argv contains
+    ``gateway run``: there should be at most one (the legitimately
+    supervised gateway). Two or more would imply recursive spawning
+    via the redirect → start → run → redirect → ... loop.
+    """
+    subprocess.run(
+        ["docker", "run", "-d", "--name", container_name, built_image,
+         "gateway", "run"],
+        check=True, capture_output=True, timeout=30,
+    )
+    time.sleep(6)
+
+    # Count python processes running `hermes gateway run`. If the
+    # recursion guard fails, s6 would respawn fresh `gateway run`
+    # processes on every cycle, leaving multiple Python-process
+    # descendants under the gateway-default supervise tree.
+    r = _sh(container_name, "ps -eo pid,cmd | grep -v grep | grep -E 'python.*hermes.*gateway run' | wc -l")
+    assert r.returncode == 0
+    n = int(r.stdout.strip() or 0)
+    assert n <= 1, (
+        f"expected at most one supervised python `hermes gateway run` "
+        f"process (the legitimately-supervised gateway); found {n}. "
+        f"Recursion guard may have failed. "
+        f"ps:\n{_sh(container_name, 'ps -eo pid,ppid,cmd').stdout}"
+    )
+
+    # Stronger positive assertion: there should be exactly one
+    # `sleep infinity` process whose parent is the main-wrapper.sh
+    # CMD process (PID 17 typically). The static `main-hermes`
+    # service has its own `sleep infinity` child; THAT one is fine
+    # and unrelated to our redirect.
+    r = _sh(
+        container_name,
+        # Find PID of the CMD process (main-wrapper.sh or its sh
+        # parent), then count `sleep infinity` children.
+        "ps -eo pid,ppid,cmd | grep -v grep | awk '/main-wrapper.sh|rc.init top/ { wrapper_pid=$1 } "
+        "$3==\"sleep\" && $4==\"infinity\" && $2==wrapper_pid { c++ } END { print c+0 }'",
+    )
+    assert r.returncode == 0
+    redirected = int(r.stdout.strip() or 0)
+    assert redirected == 1, (
+        f"expected exactly one `sleep infinity` parented to the CMD "
+        f"wrapper (the redirect heartbeat); found {redirected}. "
+        f"ps:\n{_sh(container_name, 'ps -eo pid,ppid,cmd').stdout}"
+    )
+
+
+def test_dashboard_supervised_when_env_set(
+    built_image: str, container_name: str,
+) -> None:
+    """When ``HERMES_DASHBOARD=1`` is set, ``docker run <image> gateway
+    run`` should result in BOTH the gateway and the dashboard being
+    supervised by s6 — the dashboard slot was always there but only
+    activates with the env var. This is the headline benefit of the
+    redirect: one container = supervised gateway + supervised
+    dashboard, with zero extra user effort.
+    """
+    subprocess.run(
+        ["docker", "run", "-d", "--name", container_name,
+         "-e", "HERMES_DASHBOARD=1",
+         built_image, "gateway", "run"],
+        check=True, capture_output=True, timeout=30,
+    )
+    time.sleep(5)
+
+    # Both slots should report want-up.
+    assert _svstat_wants_up(container_name, "gateway-default"), (
+        f"gateway-default slot not up: {_svstat(container_name)!r}"
+    )
+    assert _svstat_wants_up(container_name, "dashboard"), (
+        f"dashboard slot not up: {_svstat(container_name, 'dashboard')!r}"
+    )
+
+
+def test_supervised_gateway_stdout_reaches_docker_logs(
+    built_image: str, container_name: str,
+) -> None:
+    """The supervised gateway's stdout — including the rich-console
+    startup banner — must reach ``docker logs``, not just the rotated
+    log file under ``${HERMES_HOME}/logs/gateways/<profile>/current``.
+
+    Without the ``1`` action directive in ``_render_log_run``, s6-log
+    swallows the gateway's stdout into the file and ``docker logs``
+    only sees stderr (Python ``logging`` defaults to stderr). That's
+    a poor user experience: the iconic "Hermes Gateway Starting…"
+    banner with the ⚕ symbol is the most visible "yes, your gateway
+    started" signal, and forcing users to ``docker exec`` + ``tail``
+    the log file just to see it is friction users don't expect.
+
+    With the ``1`` directive, s6-log forwards every line to its own
+    stdout (which propagates up through the s6-supervise pipeline to
+    /init's stdout = container stdout = ``docker logs``) AND also
+    writes a timestamped copy to the rotated file. Best of both.
+
+    We assert by looking for the literal banner glyph (``⚕``) — a
+    distinctive character that won't appear in stderr-routed
+    Python-logging output, so its presence in ``docker logs`` proves
+    the stdout-tee is working.
+    """
+    subprocess.run(
+        ["docker", "run", "-d", "--name", container_name, built_image,
+         "gateway", "run"],
+        check=True, capture_output=True, timeout=30,
+    )
+    # Banner is printed during gateway startup — give it time to
+    # initialize past the imports + config-load phase.
+    time.sleep(8)
+
+    logs = subprocess.run(
+        ["docker", "logs", container_name],
+        capture_output=True, text=True, timeout=10,
+    )
+    combined = logs.stdout + logs.stderr
+
+    # The banner ⚕ symbol is the load-bearing assertion — it's unique
+    # to gateway startup stdout output and won't appear in stderr
+    # (Python logging) or s6 boot messages.
+    assert "⚕" in combined or "Hermes Gateway Starting" in combined, (
+        "Supervised gateway's stdout banner did not reach docker logs. "
+        "This means the `1` action directive in _render_log_run isn't "
+        "forwarding stdout to /init. "
+        f"docker logs (last 2000 chars):\n{combined[-2000:]}\n"
+        f"file contents:\n{_sh(container_name, 'cat /opt/data/logs/gateways/default/current').stdout}"
+    )
+
+    # Cross-check: the same banner must also be in the rotated log
+    # file (we kept the file destination, just added stdout). The
+    # file version has s6-log's ISO 8601 timestamp prefix; the
+    # docker logs version is raw.
+    file_contents = _sh(
+        container_name, "cat /opt/data/logs/gateways/default/current",
+    ).stdout
+    assert "⚕" in file_contents or "Hermes Gateway Starting" in file_contents, (
+        "Banner also missing from rotated log file — the file "
+        "destination may have been dropped by the new s6-log script. "
+        f"File contents:\n{file_contents}"
+    )
+

tests/docker/test_main_invocation.py

@@ -0,0 +1,79 @@
+"""Harness: docker run <image> [cmd...] invocation patterns.
+
+These tests MUST pass on the current tini-based image AND continue to
+pass after the Phase 2 s6 migration. Any behavior drift is a regression.
+
+The harness expects ``built_image`` and ``container_name`` fixtures from
+``tests/docker/conftest.py``. When Docker isn't available every test
+here is skipped at collection time.
+"""
+from __future__ import annotations
+
+import subprocess
+
+
+def test_no_args_starts_hermes(built_image: str) -> None:
+    """``docker run <image>`` should start hermes cleanly.
+
+    We invoke ``--version`` so the call exits without needing a configured
+    model. Exit code may be 0 (printed version) or 1 (config bootstrapping
+    failure on a fresh volume), but never a stack trace.
+    """
+    r = subprocess.run(
+        ["docker", "run", "--rm", built_image, "--version"],
+        capture_output=True, text=True, timeout=60,
+    )
+    assert r.returncode in (0, 1), (
+        f"Unexpected exit {r.returncode}: stderr={r.stderr!r}"
+    )
+    assert "Traceback" not in r.stderr
+
+
+def test_chat_subcommand_passthrough(built_image: str) -> None:
+    """``docker run <image> chat --help`` should exec ``hermes chat --help``.
+
+    Uses ``--help`` so the call doesn't need an upstream model configured.
+    """
+    r = subprocess.run(
+        ["docker", "run", "--rm", built_image, "chat", "--help"],
+        capture_output=True, text=True, timeout=60,
+    )
+    assert r.returncode == 0
+    combined = (r.stdout + r.stderr).lower()
+    assert "chat" in combined or "usage" in combined
+
+
+def test_bare_executable_passthrough(built_image: str) -> None:
+    """``docker run <image> sleep 1`` should exec ``sleep`` directly.
+
+    The entrypoint detects that ``sleep`` is on PATH and routes around the
+    hermes wrapper. Useful for long-lived sandbox mode and for testing.
+    """
+    r = subprocess.run(
+        ["docker", "run", "--rm", built_image, "sleep", "1"],
+        capture_output=True, text=True, timeout=30,
+    )
+    assert r.returncode == 0
+
+
+def test_bash_pattern(built_image: str) -> None:
+    """``docker run <image> bash -c 'echo ok'`` should exec bash directly."""
+    r = subprocess.run(
+        ["docker", "run", "--rm", built_image, "bash", "-c", "echo ok"],
+        capture_output=True, text=True, timeout=30,
+    )
+    assert r.returncode == 0
+    assert "ok" in r.stdout
+
+
+def test_container_exit_code_matches_inner_exit(built_image: str) -> None:
+    """The container exit code must match the inner process's exit code.
+
+    Critical for CI: ``docker run <image> hermes batch ...`` returns a
+    non-zero status when batch fails. Phase 2 (s6) must preserve this.
+    """
+    r = subprocess.run(
+        ["docker", "run", "--rm", built_image, "sh", "-c", "exit 42"],
+        capture_output=True, text=True, timeout=30,
+    )
+    assert r.returncode == 42

tests/docker/test_profile_gateway.py

@@ -0,0 +1,138 @@
+"""Harness: per-profile gateway start/stop inside the container.
+
+Phase 4 wires `hermes -p <profile> gateway start/stop` through the s6
+ServiceManager dispatch path inside the container — so the lifecycle
+commands now bring up an s6-supervised gateway rather than refusing
+with the pre-Phase-4 informational message.
+
+These tests were marked ``xfail(strict=True)`` through Phase 0–3 and
+flip to plain ``test_…`` once Phase 4 lands (now).
+
+NB: The harness profile has no model/auth configured. Depending on
+how the gateway run script handles missing config, the supervised
+process may either spin up successfully (and svstat reports ``up``)
+or exit fast and get throttled by s6 (and svstat reports ``down …,
+want up``). Both states are valid "user asked for gateway up" results
+— what we assert is the *want* intent the lifecycle command set, NOT
+the supervised process's health. ``s6-svc -u`` records ``want up`` in
+the supervise/status file regardless of the run-script outcome.
+
+Every ``docker exec`` here runs as the unprivileged ``hermes`` user
+(via :func:`docker_exec_sh` in conftest); see the conftest module
+docstring.
+"""
+from __future__ import annotations
+
+import subprocess
+import time
+
+from tests.docker.conftest import docker_exec_sh
+
+PROFILE = "test-harness-profile"
+
+
+def _sh(
+    container: str, command: str, timeout: int = 30,
+) -> subprocess.CompletedProcess[str]:
+    return docker_exec_sh(container, command, timeout=timeout)
+
+
+def _svstat(container: str) -> str:
+    """Returns the raw s6-svstat output for the test profile's slot.
+    /command/s6-svstat is called by absolute path because /command/
+    isn't on PATH for docker-exec sessions."""
+    r = _sh(container, f"/command/s6-svstat /run/service/gateway-{PROFILE}")
+    return r.stdout if r.returncode == 0 else ""
+
+
+def _svstat_wants_up(container: str) -> bool:
+    """Read the slot's want-state from s6-svstat output.
+
+    s6-svstat formats the output to elide redundancies — when the
+    service is currently up AND s6 wants it up, the literal token
+    ``want up`` doesn't appear (it's implicit from the leading ``up``).
+    When the service is down but s6 wants it back up, ``, want up``
+    appears explicitly. So a comprehensive "is the want-intent set to
+    up" check has to accept both spellings.
+    """
+    state = _svstat(container)
+    if not state:
+        return False
+    head = state.split()[0] if state.split() else ""
+    if head == "up":
+        # Currently up implies wanted-up unless ``want down`` is set.
+        return "want down" not in state
+    # Currently down — ``want up`` only shows up when explicitly set.
+    return "want up" in state
+
+
+def test_profile_create_then_gateway_start(
+    built_image: str, container_name: str,
+) -> None:
+    subprocess.run(
+        ["docker", "run", "-d", "--name", container_name, built_image,
+         "sleep", "120"],
+        check=True, capture_output=True, timeout=30,
+    )
+    time.sleep(3)
+
+    r = _sh(container_name, f"hermes profile create {PROFILE}")
+    assert r.returncode == 0, f"profile create failed: {r.stderr}"
+
+    # Profile create's s6-register hook should have produced a service slot.
+    r = _sh(container_name, f"test -d /run/service/gateway-{PROFILE}")
+    assert r.returncode == 0, "s6 service slot not created on profile create"
+
+    r = _sh(container_name, f"hermes -p {PROFILE} gateway start", timeout=60)
+    assert r.returncode == 0, (
+        f"gateway start failed: stderr={r.stderr!r} stdout={r.stdout!r}"
+    )
+
+    # After start, s6's intent is "up" — even if the supervised gateway
+    # process spin-fails (no model/auth in the test profile), the
+    # supervision-state contract holds. See ``_svstat_wants_up`` for
+    # why we accept both ``up …`` (currently up) and ``down …, want
+    # up`` (down but s6 wants up).
+    time.sleep(2)
+    assert _svstat_wants_up(container_name), (
+        f"slot want-state is not up after gateway start: "
+        f"{_svstat(container_name)!r}"
+    )
+
+    r = _sh(container_name, f"hermes -p {PROFILE} gateway stop", timeout=30)
+    assert r.returncode == 0
+
+    time.sleep(2)
+    assert not _svstat_wants_up(container_name), (
+        f"slot want-state still up after gateway stop: "
+        f"{_svstat(container_name)!r}"
+    )
+
+
+def test_profile_delete_stops_gateway(
+    built_image: str, container_name: str,
+) -> None:
+    """Deleting a profile should stop its gateway and remove the s6
+    service slot."""
+    subprocess.run(
+        ["docker", "run", "-d", "--name", container_name, built_image,
+         "sleep", "120"],
+        check=True, capture_output=True, timeout=30,
+    )
+    time.sleep(3)
+
+    _sh(container_name, f"hermes profile create {PROFILE}")
+    _sh(container_name, f"hermes -p {PROFILE} gateway start", timeout=60)
+    time.sleep(3)
+
+    r = _sh(
+        container_name,
+        f"hermes profile delete {PROFILE} --yes",
+        timeout=30,
+    )
+    assert r.returncode == 0, f"profile delete failed: {r.stderr}"
+
+    time.sleep(2)
+    # Service slot should be gone.
+    r = _sh(container_name, f"test -d /run/service/gateway-{PROFILE}")
+    assert r.returncode != 0, "s6 service slot still present after profile delete"

tests/docker/test_s6_profile_gateway_integration.py

@@ -0,0 +1,129 @@
+"""Harness: in-container integration tests for S6ServiceManager.
+
+The unit tests in tests/hermes_cli/test_service_manager.py exercise the
+class against a tmp-path scandir with a stubbed ``subprocess.run``.
+These tests run the real class inside a real container against the
+real s6-svc / s6-svscanctl binaries, validating end-to-end.
+
+Phase 3 only registers the service slot — it doesn't depend on the
+gateway actually starting (the binary will refuse to start without a
+valid profile config). The full register → start → supervised-restart
+→ unregister cycle is covered by Phase 4 once profile create/delete
+hooks land.
+
+Every ``docker exec`` here runs as the unprivileged ``hermes`` user
+(via :func:`docker_exec` in conftest); see the conftest module
+docstring. ``/run/service`` is chowned hermes-writable by the
+``02-reconcile-profiles`` cont-init.d script, so register/unregister
+operations work correctly under UID 10000.
+"""
+from __future__ import annotations
+
+import subprocess
+import time
+
+from tests.docker.conftest import docker_exec
+
+
+_REGISTER_SCRIPT = """
+import sys
+sys.path.insert(0, "/opt/hermes")
+from hermes_cli.service_manager import S6ServiceManager
+S6ServiceManager().register_profile_gateway("phase3test")
+# Don't worry about whether the gateway actually starts — we only care
+# that the supervision slot was created. The gateway run script will
+# likely error out (no profile config exists) but that's expected.
+print("REGISTERED")
+"""
+
+_UNREGISTER_SCRIPT = """
+import sys
+sys.path.insert(0, "/opt/hermes")
+from hermes_cli.service_manager import S6ServiceManager
+S6ServiceManager().unregister_profile_gateway("phase3test")
+print("UNREGISTERED")
+"""
+
+
+def _exec(container: str, *args: str, timeout: int = 30) -> subprocess.CompletedProcess:
+    return docker_exec(container, *args, timeout=timeout)
+
+
+def test_s6_register_creates_service_dir_in_live_container(
+    built_image: str, container_name: str,
+) -> None:
+    """S6ServiceManager.register_profile_gateway must create
+    ``/run/service/gateway-<profile>/`` and trigger s6-svscan rescan
+    against the real s6 supervision tree."""
+    subprocess.run(
+        ["docker", "run", "-d", "--name", container_name, built_image,
+         "sleep", "120"],
+        check=True, capture_output=True, timeout=30,
+    )
+    # Give the supervision tree a moment to come up.
+    time.sleep(3)
+
+    r = _exec(container_name, "python3", "-c", _REGISTER_SCRIPT, timeout=30)
+    assert "REGISTERED" in r.stdout, (
+        f"register failed: stderr={r.stderr!r} stdout={r.stdout!r}"
+    )
+
+    # Service directory exists with the expected structure.
+    r = _exec(container_name, "test", "-d", "/run/service/gateway-phase3test")
+    assert r.returncode == 0, "service directory not created"
+
+    r = _exec(container_name, "test", "-f", "/run/service/gateway-phase3test/run")
+    assert r.returncode == 0, "run script not created"
+
+    r = _exec(container_name, "test", "-f",
+              "/run/service/gateway-phase3test/log/run")
+    assert r.returncode == 0, "log/run script not created"
+
+    # s6-svscan picked it up — s6-svstat works against the dir.
+    # `docker exec` doesn't put /command/ on PATH (only the supervision
+    # tree does), so call s6-svstat by absolute path.
+    r = _exec(container_name, "/command/s6-svstat",
+              "/run/service/gateway-phase3test")
+    assert r.returncode == 0, f"s6-svstat failed: {r.stderr or r.stdout}"
+
+    # list_profile_gateways picks it up.
+    r = _exec(container_name, "python3", "-c", (
+        "from hermes_cli.service_manager import S6ServiceManager;"
+        "print(S6ServiceManager().list_profile_gateways())"
+    ))
+    assert "phase3test" in r.stdout, f"list output: {r.stdout!r}"
+
+
+def test_s6_unregister_removes_service_dir_in_live_container(
+    built_image: str, container_name: str,
+) -> None:
+    """unregister_profile_gateway must stop the service, remove the
+    directory, and trigger s6-svscan rescan so the supervise process
+    is dropped."""
+    subprocess.run(
+        ["docker", "run", "-d", "--name", container_name, built_image,
+         "sleep", "120"],
+        check=True, capture_output=True, timeout=30,
+    )
+    time.sleep(3)
+
+    # First register so we have something to unregister.
+    r = _exec(container_name, "python3", "-c", _REGISTER_SCRIPT, timeout=30)
+    assert "REGISTERED" in r.stdout
+
+    # Then unregister.
+    r = _exec(container_name, "python3", "-c", _UNREGISTER_SCRIPT, timeout=30)
+    assert "UNREGISTERED" in r.stdout, (
+        f"unregister failed: stderr={r.stderr!r} stdout={r.stdout!r}"
+    )
+
+    # Directory is gone.
+    r = _exec(container_name, "test", "-d", "/run/service/gateway-phase3test")
+    assert r.returncode != 0, "service directory still exists after unregister"
+
+    # list_profile_gateways no longer includes it.
+    r = _exec(container_name, "python3", "-c", (
+        "from hermes_cli.service_manager import S6ServiceManager;"
+        "print(S6ServiceManager().list_profile_gateways())"
+    ))
+    assert "phase3test" not in r.stdout

tests/docker/test_tui_passthrough.py

@@ -0,0 +1,65 @@
+"""Harness: interactive TUI TTY passthrough.
+
+Uses ``script -qc`` on the host to allocate a PTY for the docker client,
+which then allocates a container-side PTY via ``-t``. The probe inside
+the container is ``tput cols``, which returns a real column count when
+stdout is a TTY and either prints ``80`` (the terminfo fallback) or
+nothing when it is not.
+
+These tests MUST pass on the current tini-based image AND continue to
+pass after the Phase 2 s6 migration. Any drift is a regression.
+"""
+from __future__ import annotations
+
+import re
+import shlex
+import shutil
+import subprocess
+
+import pytest
+
+pytestmark = pytest.mark.skipif(
+    shutil.which("script") is None,
+    reason="`script` command not available on this host",
+)
+
+
+def test_tty_passthrough_to_container(built_image: str) -> None:
+    """``docker run -t`` must deliver a real TTY to the container process."""
+    # Emit the probe result behind a unique marker. The container's s6 boot
+    # output (cont-init diagnostics, skills-sync summaries like
+    # "Done: 90 new, 0 updated, ...", the preinit "uid=0 ... egid=0" line)
+    # is written to the SAME PTY stream before this runs, so we must NOT
+    # scan the whole stream for "the first number" — that picks up a stray
+    # 0 from the boot log and flips the assertion (assert 0 > 0) whenever
+    # boot output shifts (e.g. a new bundled dep changes the skills-sync
+    # counts). Parse only the value tagged with our marker.
+    marker = "HERMES_TTY_COLS"
+    probe = (
+        f'if [ -t 1 ]; then echo "{marker}=$(tput cols)"; else echo "{marker}=NO_TTY"; fi'
+    )
+    cmd = (
+        f"docker run --rm -t -e COLUMNS=123 {built_image} "
+        f"sh -c {shlex.quote(probe)}"
+    )
+    r = subprocess.run(
+        ["script", "-qc", cmd, "/dev/null"],
+        capture_output=True, text=True, timeout=120,
+    )
+    output = r.stdout
+    matches = re.findall(rf"{marker}=(\S+)", output)
+    assert matches, f"No {marker} marker in output: {output!r}"
+    value = matches[-1].strip()
+    assert value != "NO_TTY", f"TTY passthrough failed: {output!r}"
+    assert value.isdigit(), f"Non-numeric column width {value!r} in: {output!r}"
+    assert int(value) > 0
+
+
+def test_tui_flag_recognized(built_image: str) -> None:
+    """``docker run -it <image> --help`` should run without crashing."""
+    cmd = f"docker run --rm -t {built_image} --help"
+    r = subprocess.run(
+        ["script", "-qc", cmd, "/dev/null"],
+        capture_output=True, text=True, timeout=60,
+    )
+    assert r.returncode == 0

tests/docker/test_tui_prebuilt_bundle.py

@@ -0,0 +1,79 @@
+"""Harness: the image ships a prebuilt TUI bundle, not a runtime npm install.
+
+Regression guard for the hosted-chat failure where the embedded dashboard
+Chat tab died with a 502 / "[session ended]". Root cause: the image installs
+only a subset of the npm monorepo workspaces (root/web/ui-tui, never apps/*),
+so the actualized node_modules permanently disagrees with the canonical
+package-lock.json. Without HERMES_TUI_DIR set, ``_make_tui_argv`` falls
+through to ``_tui_need_npm_install`` (which returns True forever) and tries a
+runtime ``npm install`` that can never converge and races itself across
+concurrent /api/pty connections → ENOTEMPTY.
+
+The fix is ``ENV HERMES_TUI_DIR=/opt/hermes/ui-tui`` in the Dockerfile, which
+makes the launcher take the prebuilt-bundle fast path (``node --expose-gc
+.../dist/entry.js``) and skip the install check entirely. These tests assert
+that invariant holds in the built image.
+"""
+from __future__ import annotations
+
+import json
+import shlex
+import subprocess
+
+
+def _exec_py(image: str, py: str) -> str:
+    """Run a Python snippet inside the image as the hermes user, return stdout."""
+    inner = (
+        "source /opt/hermes/.venv/bin/activate && "
+        "cd /opt/hermes && "
+        f"python3 -c {shlex.quote(py)}"
+    )
+    # Drop to the hermes user (UID 10000) so we exercise the same path the
+    # dashboard PTY child runs as — not root.
+    cmd = [
+        "docker", "run", "--rm", "--entrypoint", "su", image,
+        "hermes", "-s", "/bin/bash", "-c", inner,
+    ]
+    r = subprocess.run(cmd, capture_output=True, text=True, timeout=120)
+    assert r.returncode == 0, f"in-container python failed:\n{r.stderr[-2000:]}"
+    return r.stdout.strip()
+
+
+def test_hermes_tui_dir_env_is_set(built_image: str) -> None:
+    """HERMES_TUI_DIR must point at the prebuilt bundle dir in the image."""
+    r = subprocess.run(
+        ["docker", "run", "--rm", "--entrypoint", "sh", built_image,
+         "-c", 'printf "%s" "$HERMES_TUI_DIR"'],
+        capture_output=True, text=True, timeout=60,
+    )
+    assert r.returncode == 0, r.stderr[-2000:]
+    assert r.stdout.strip() == "/opt/hermes/ui-tui", (
+        f"HERMES_TUI_DIR={r.stdout.strip()!r} (expected /opt/hermes/ui-tui)"
+    )
+
+
+def test_prebuilt_bundle_present_and_no_runtime_install(built_image: str) -> None:
+    """The launcher must (a) find the prebuilt bundle and (b) NOT want an
+    npm install — i.e. it takes the same path as a nix/packaged release."""
+    py = (
+        "import json\n"
+        "from pathlib import Path\n"
+        "from hermes_cli.main import _tui_need_npm_install, _find_bundled_tui, _make_tui_argv\n"
+        "ui = Path('/opt/hermes/ui-tui')\n"
+        "argv, cwd = _make_tui_argv(ui, tui_dev=False)\n"
+        "out = {\n"
+        "  'dist_entry_exists': (ui / 'dist' / 'entry.js').is_file(),\n"
+        "  'need_npm_install': _tui_need_npm_install(ui),\n"
+        "  'argv': argv,\n"
+        "  'uses_prebuilt': ('dist/entry.js' in ' '.join(argv)) and ('npm' not in argv[0].lower()),\n"
+        "}\n"
+        "print(json.dumps(out))\n"
+    )
+    out = json.loads(_exec_py(built_image, py))
+    assert out["dist_entry_exists"], "prebuilt ui-tui/dist/entry.js missing from image"
+    # With HERMES_TUI_DIR set, _make_tui_argv returns the prebuilt path BEFORE
+    # ever reaching the install check — so the resolved argv is what matters.
+    assert out["uses_prebuilt"], f"launcher did not take prebuilt path: argv={out['argv']!r}"
+    assert "npm" not in out["argv"][0].lower(), (
+        f"launcher resolved to an npm invocation, not the prebuilt bundle: {out['argv']!r}"
+    )

tests/docker/test_zombie_reaping.py

@@ -0,0 +1,45 @@
+"""Harness: PID 1 must reap orphaned zombie processes.
+
+tini (current PID 1) reaps zombies via its built-in subreaper behavior.
+s6-overlay's ``/init`` (Phase 2 PID 1) does the same. This invariant is
+required for long-running containers spawning subprocesses (subagents,
+dashboard, dynamic gateways) — otherwise the process table fills with
+defunct entries and eventually exhausts the kernel PID space.
+
+Every ``docker exec`` here runs as the unprivileged ``hermes`` user
+(via :func:`docker_exec_sh` in conftest); see the conftest module
+docstring.
+"""
+from __future__ import annotations
+
+import subprocess
+import time
+
+from tests.docker.conftest import docker_exec, docker_exec_sh
+
+
+def test_orphan_zombies_reaped(
+    built_image: str, container_name: str,
+) -> None:
+    """Spawn an orphan child that exits immediately. PID 1 must reap it."""
+    subprocess.run(
+        ["docker", "run", "-d", "--name", container_name, built_image,
+         "sleep", "60"],
+        check=True, capture_output=True, timeout=30,
+    )
+    time.sleep(2)
+
+    # `( ( sleep 0.1 & ) & ); sleep 1` creates a grandchild detached from
+    # the original docker exec session — it becomes an orphan reparented
+    # to PID 1 in the container. When it exits, PID 1 must reap it.
+    docker_exec_sh(
+        container_name, "( ( sleep 0.1 & ) & ); sleep 1", timeout=10,
+    )
+    time.sleep(1)
+
+    r = docker_exec(container_name, "ps", "axo", "stat,pid,comm")
+    zombies = [
+        line for line in r.stdout.split("\n")
+        if line.strip().startswith("Z")
+    ]
+    assert not zombies, f"Zombies not reaped by PID 1: {zombies}"