HarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.
Python agent-apiagent-frameworkagent-harnessai-agentsai-infrastructurecoding-agentconformance-testingdeepseek-harnessharness-engineeringhermesllmopen-protocolopen-sourceopen-standardpi-coding-agentself-hosteduhpunified-apiunified-harness-protocolunified-interface
fix(runner): the session write-wall — an agent process may write its own session directory and nothing else
richard-epsilla9a0347f863fc
diff --git a/Dockerfile b/Dockerfileindex 0ecef572..a9a6dcb2 100644--- a/Dockerfile+++ b/Dockerfile@@ -162,8 +162,12 @@ COPY --from=ui /ui/.next/standalone /app/ui/COPY --from=ui /ui/.next/static /app/ui/.next/staticCOPY --from=ui /ui/public /app/ui/public-# The agent CLIs refuse to run as root (they gate their own permission bypass on it), so the-# runtime user is unprivileged and owns the workspace and data volume.+# `agent` is the PRODUCT's user: the gateway and the console run as it and it owns the data+# volume. The container itself starts as root and the entrypoint drops privileges per process,+# because the runner needs root for one thing: every agent CLI runs as its own per-session uid,+# which owns its session directory and nothing else (the write-wall; see docker/entrypoint.sh).+# The CLIs refuse to run as root anyway (they gate their own permission bypass on it), and they+# never do.## The `rm -rf /home/agent/.npm` is not tidying. HOME is already /home/agent while the kit apps are# built above, and those builds run as root — so npm leaves ~1600 root-owned files in the cache@@ -181,7 +185,6 @@ RUN useradd -m -u 10001 agent \&& mkdir -p /data \&& chown -R agent:agent /data /app /home/agent \&& chmod -R a+rX /opt/harnessrouter/skills /opt/harnessrouter/kits-USER agentEXPOSE 3000VOLUME ["/data"]diff --git a/docker/entrypoint.sh b/docker/entrypoint.shindex e2b0bd95..b86878bf 100644--- a/docker/entrypoint.sh+++ b/docker/entrypoint.sh@@ -6,6 +6,26 @@# that restarts. `docker run --restart` then does the recovering.set -euo pipefail+# ── privilege layout ──────────────────────────────────────────────────────────+# Three principals, and the distance between them is the product's security model:+# root this entrypoint and the runner. The runner switches to a per-session uid for every+# agent process, which is the one thing that needs root. CAP_SETUID, CAP_SETGID and+# CAP_CHOWN are in Docker's default set: no --privileged, no --cap-add.+# agent the product: the gateway, the console, the data volume. Its databases, blobs and+# secret store are readable by it alone.+# 20000+ one uid per session, owning its session directory and nothing else. /tmp, /var/tmp+# and /dev/shm are closed to those uids, so the ONLY path an agent process can write is+# its own session directory. A deliverable saved to "/tmp/deck.pptx" fails at the write,+# while the model is still there to choose the right path, instead of vanishing: the+# self-hosted reproduction of the 2026-08-21 lost-deliverable incident wrote exactly+# there. See _isolate_session in runner/server.py.+if [ "$(id -u)" -ne 0 ]; then+ echo "[harnessrouter] ERROR: the container must start as root. It drops privileges itself: the product runs as 'agent', every agent process as its own session uid. Remove --user from docker run."+ exit 1+fi+PRODUCT=agent+AS_PRODUCT="setpriv --reuid=$PRODUCT --regid=$PRODUCT --init-groups"+DATA_DIR="${HR_DATA_DIR:-/data}"mkdir -p "$DATA_DIR"@@ -15,6 +35,21 @@ mkdir -p "$DATA_DIR"export HARNESS_WORKSPACE="${HARNESS_WORKSPACE:-$DATA_DIR/workspaces}"mkdir -p "$HARNESS_WORKSPACE"+# The write-wall, in file modes. Idempotent and non-recursive, so it costs nothing on a volume+# that already has it and repairs one that predates it. Session directories themselves are owned+# by their session's uid (0700); the runner sets that as it allocates them.+chown "$PRODUCT:$PRODUCT" "$DATA_DIR" "$HARNESS_WORKSPACE"+chmod 751 "$DATA_DIR" "$HARNESS_WORKSPACE" # traversable by sessions, neither listable nor writable+for f in "$DATA_DIR"/*.db "$DATA_DIR"/*.db-* "$DATA_DIR"/selfhost-auth.json; do+ if [ -e "$f" ]; then chown "$PRODUCT:$PRODUCT" "$f"; chmod 600 "$f"; fi+done+for d in "$DATA_DIR/blobs" "$DATA_DIR/secrets"; do+ if [ -d "$d" ]; then chown "$PRODUCT:$PRODUCT" "$d"; chmod 700 "$d"; fi+done+for d in /tmp /var/tmp /dev/shm; do+ if [ -d "$d" ]; then chown "root:$PRODUCT" "$d"; chmod 1770 "$d"; fi+done+# Our own processes must run on the image's interpreter, never on whatever a backend puts on# PATH. Hermes installs into its own venv and that venv's bin joins PATH below so the runner can# spawn `hermes` — but that venv has none of the gateway's dependencies, so resolving `python3`@@ -263,12 +298,16 @@ if [ -n "$missing" ]; thenecho "[harnessrouter] WARN: requested but not installed:$missing — those backends cannot run"fi-# runner (loopback only)-( cd /app/runner && exec "$PY" -m uvicorn server:app --host 127.0.0.1 --port 8081 --log-level warning ) &+# runner (loopback only). Root, for the per-session uid switch; HR_SESSION_UIDS=1 is the+# declaration the runner fails closed without. The console's credentials and the secret-store key+# are the product's and are not in its environment at all.+( cd /app/runner && exec env -u HR_AUTH_USER -u HR_AUTH_PASSWORD -u HR_AUTH_STORE -u HR_SECRET_KEY \+ HR_SESSION_UIDS=1 "$PY" -m uvicorn server:app --host 127.0.0.1 --port 8081 --log-level warning ) &pids+=($!)-# gateway (loopback only)-( cd /app/gateway && exec "$PY" -m uvicorn app:app --host 127.0.0.1 --port 8080 --log-level warning ) &+# gateway (loopback only), as the product. umask 077: what it creates on the volume (databases,+# blobs, the secret store) is its alone.+( cd /app/gateway && exec $AS_PRODUCT sh -c 'umask 077; exec "$0" -m uvicorn app:app --host 127.0.0.1 --port 8080 --log-level warning' "$PY" ) &pids+=($!)# Wait for the gateway before the UI starts serving, so a first page load never races a@@ -293,7 +332,7 @@ donewhile :; doHR_SESSION_KEY="$(hr_session_key)" \HR_AUTH_USER="$(hr_stored_user)" \- node server.js+ $AS_PRODUCT sh -c 'umask 077; exec node server.js'status=$?# A clean exit is the credential change asking for a restart. Anything else is a real# failure, and repeating it forever would hide it — so give up and let the container die.diff --git a/gateway/app.py b/gateway/app.pyindex c27f2be9..c977abcb 100644--- a/gateway/app.py+++ b/gateway/app.py@@ -1132,9 +1132,14 @@ async def _mapped_integration_conn(backend: str, canonical: str) -> dict | None:# ── pool proxy ───────────────────────────────────────────────────────────────────def _pool_headers() -> dict:- """Auth headers for the runner. Empty when local — no cloud identity exists or is needed."""+ """Auth headers for the runner: the cloud identity token through a session pool; beside a local+ runner, the internal key. Behind the self-hosted write-wall (HR_SESSION_UIDS) the runner refuses+ callers without it, because every agent process shares its loopback and its routes address any+ session by identifier."""tok = _pool_token()- return {"Authorization": f"Bearer {tok}"} if tok else {}+ if tok:+ return {"Authorization": f"Bearer {tok}"}+ return {"X-Harness-Internal": INTERNAL_KEY} if INTERNAL_KEY else {}async def _sandbox(path: str, sid: str, method: str = "POST", body: dict | None = None,diff --git a/gateway/backing.py b/gateway/backing.pyindex f07d71b4..dd2e27ae 100644--- a/gateway/backing.py+++ b/gateway/backing.py@@ -31,7 +31,6 @@ import secrets as secrets_modimport ioimport jsonimport os-import pathlibimport posixpathimport reimport sqlite3@@ -41,6 +40,8 @@ import uuidfrom pathlib import Pathfrom typing import Protocol+import httpx+# ── interfaces ────────────────────────────────────────────────────────────────────class GraphStore(Protocol):@@ -369,49 +370,52 @@ def _safe_member(path: str) -> str | None:return p-class LocalWorkspaceFiles:- """Self-hosted: the workspace is a live directory on the data volume, shared with the runner- in this container. Writes land where the agent will read them on its next turn."""+class RunnerWorkspaceFiles:+ """Self-hosted: a session's workspace is a live directory on the data volume, and the RUNNER is+ the only principal that touches it. Behind the write-wall each session directory belongs to that+ session's own uid and the product deliberately cannot read or write there (see _isolate_session+ in the runner), so a live read or write goes through the runner, which acts as the session,+ rather than through this process's own filesystem access. One door, whether the wall is up or+ not: the runner is beside the gateway in every self-hosted deployment.- def __init__(self, root: str):- self.root = root+ Live, unlike the checkpoint the listing route reads: an app sees a file the moment a tool call+ creates it, rather than when the turn ends."""- def _path(self, sid: str, path: str) -> str | None:- member = _safe_member(path)- if not member or not sid or "/" in sid or sid in (".", ".."):- return None- base = os.path.realpath(os.path.join(self.root, sid))- full = os.path.realpath(os.path.join(base, member))- # Resolve first, then prove containment: checking the input for '..' misses symlinks.- return full if full == base or full.startswith(base + os.sep) else None+ def __init__(self, endpoint: str, key: str):+ self.endpoint = (endpoint or "").rstrip("/")+ self.key = key+ self._client: httpx.AsyncClient | None = None++ def _c(self) -> httpx.AsyncClient:+ if self._client is None:+ self._client = httpx.AsyncClient(timeout=httpx.Timeout(60.0, connect=5.0))+ return self._client++ def _headers(self) -> dict:+ return {"X-Harness-Internal": self.key} if self.key else {}async def read(self, sid: str, path: str) -> bytes | None:- full = self._path(sid, path)- if not full:+ member = _safe_member(path)+ if not member or not self.endpoint:return Nonetry:- return await asyncio.to_thread(pathlib.Path(full).read_bytes)- except OSError:+ r = await self._c().get(f"{self.endpoint}/file", params={"identifier": sid, "path": member},+ headers=self._headers())+ except Exception: # noqa: BLE001 — a runner that is down reads as "no file", never a 500return None+ return r.content if r.status_code == 200 else Noneasync def write(self, sid: str, path: str, data: bytes) -> bool:- full = self._path(sid, path)- if not full:+ member = _safe_member(path)+ if not member or not self.endpoint:return False-- def _put() -> bool:- try:- os.makedirs(os.path.dirname(full), exist_ok=True)- # Write beside, then rename: a reader (the agent, mid-turn) sees either the old- # file or the new one, never a half-written one.- tmp = f"{full}.tmp-{uuid.uuid4().hex[:8]}"- with open(tmp, "wb") as fh:- fh.write(data)- os.replace(tmp, full)- return True- except OSError:- return False- return await asyncio.to_thread(_put)+ try:+ r = await self._c().put(f"{self.endpoint}/file", params={"identifier": sid, "path": member},+ headers={**self._headers(), "content-type": "application/octet-stream"},+ content=data)+ except Exception: # noqa: BLE001+ return False+ return r.status_code == 200class CheckpointWorkspaceFiles:@@ -488,9 +492,8 @@ def make_backing(*, client_getter, vg_url: str, vg_key: str, vg_tenant: str,configured (production), local otherwise (a laptop clone works with zero env)."""mode = os.environ.get("HR_BACKING", "").strip().lower() or ("vg" if vg_url else "local")# Where a session's workspace actually lives, which is the one thing that differs most between- # the two deployments: a live directory this container shares with the runner, or a checkpoint- # tarball that is the only copy between turns.- ws_root = os.environ.get("HARNESS_WORKSPACE", "/data/workspaces")+ # the two deployments: a live directory the runner owns and serves, or a checkpoint tarball+ # that is the only copy between turns.ws_key = lambda sid: f"sessions/{sid}/workspace.tgz" # noqa: E731 — matches gateway._ws_blobif mode == "vg":from backing_vg import VgBlobStore, VgGraphStore, VaultSecretStore@@ -507,4 +510,5 @@ def make_backing(*, client_getter, vg_url: str, vg_key: str, vg_tenant: str,blob=FileBlobStore(os.path.join(data, "blobs")),secrets=FileSecretStore(os.path.join(data, "secrets")),mode="local",- workspace=LocalWorkspaceFiles(ws_root))+ workspace=RunnerWorkspaceFiles(os.environ.get("POOL_MGMT_ENDPOINT", "http://127.0.0.1:8081"),+ os.environ.get("HARNESS_INTERNAL_KEY", "")))diff --git a/gateway/tests/fs_workspace.py b/gateway/tests/fs_workspace.pynew file mode 100644index 00000000..d04a3dfc--- /dev/null+++ b/gateway/tests/fs_workspace.py@@ -0,0 +1,53 @@+"""A workspace that IS a directory, for tests.++Production has two: the runner-backed one self-hosted (the session directory belongs to the+session's own uid, so only the runner may touch it) and the checkpoint-backed one on the hosted+side. Neither is a plain directory this process can write, and a media test wants to assert on+real bytes on real disk. So the double lives here rather than a third implementation living in+the product for tests to borrow."""+import asyncio+import os+import pathlib+import sys++sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))+from backing import _safe_member # noqa: E402+++class FsWorkspaceFiles:+ def __init__(self, root: str):+ self.root = root++ def _path(self, sid: str, path: str) -> str | None:+ member = _safe_member(path)+ if not member or not sid or "/" in sid or sid in (".", ".."):+ return None+ base = os.path.realpath(os.path.join(self.root, sid))+ full = os.path.realpath(os.path.join(base, member))+ return full if full == base or full.startswith(base + os.sep) else None++ async def read(self, sid: str, path: str) -> bytes | None:+ full = self._path(sid, path)+ if not full:+ return None+ try:+ return await asyncio.to_thread(pathlib.Path(full).read_bytes)+ except OSError:+ return None++ async def write(self, sid: str, path: str, data: bytes) -> bool:+ full = self._path(sid, path)+ if not full:+ return False++ def _put() -> bool:+ try:+ os.makedirs(os.path.dirname(full), exist_ok=True)+ tmp = f"{full}.tmp"+ with open(tmp, "wb") as fh:+ fh.write(data)+ os.replace(tmp, full)+ return True+ except OSError:+ return False+ return await asyncio.to_thread(_put)diff --git a/gateway/tests/test_media_attack.py b/gateway/tests/test_media_attack.pyindex 08eb015e..46316da0 100644--- a/gateway/tests/test_media_attack.py+++ b/gateway/tests/test_media_attack.py@@ -38,6 +38,8 @@ from pathlib import Pathimport httpximport pytest+from fs_workspace import FsWorkspaceFiles+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))# Set BEFORE importing app: the backing, the internal key and the encryption passphrase are all@@ -221,7 +223,7 @@ def _connect_provider(key: str = PROVIDER_KEY) -> None:@pytest.fixture(scope="module", autouse=True)def integration(client):_connect_provider()- app.BACKING.workspace = app.backing.LocalWorkspaceFiles(os.path.join(_DATA, "workspaces"))+ app.BACKING.workspace = FsWorkspaceFiles(os.path.join(_DATA, "workspaces"))return Truediff --git a/gateway/tests/test_media_mcp.py b/gateway/tests/test_media_mcp.pyindex a6963132..f236e702 100644--- a/gateway/tests/test_media_mcp.py+++ b/gateway/tests/test_media_mcp.py@@ -32,6 +32,8 @@ from pathlib import Pathimport httpximport pytest+from fs_workspace import FsWorkspaceFiles+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))# Set BEFORE importing app: the backing, the internal key and the encryption passphrase are all@@ -383,7 +385,7 @@ def integration(api):# Self-hosted, a workspace is a live directory, and its root is read at import time from# HARNESS_WORKSPACE. Bound here to THIS file's temp dir so the projection is real wherever the# process happened to start — a projection that silently lands nowhere asserts nothing.- app.BACKING.workspace = app.backing.LocalWorkspaceFiles(os.path.join(_DATA, "workspaces"))+ app.BACKING.workspace = FsWorkspaceFiles(os.path.join(_DATA, "workspaces"))return Truediff --git a/runner/dsh_driver.py b/runner/dsh_driver.pyindex 4d9b8a4d..956cb6a7 100644--- a/runner/dsh_driver.py+++ b/runner/dsh_driver.py@@ -22,7 +22,6 @@ import http.serverimport jsonimport osimport pathlib-import socketimport sysimport threadingimport urllib.requestdiff --git a/runner/server.py b/runner/server.pyindex 1b107776..00ae20bf 100644--- a/runner/server.py+++ b/runner/server.py@@ -56,6 +56,9 @@ import socketimport sqlite3import subprocessimport tempfile+import hmac+import pwd+import statimport threadingimport timeimport urllib.error@@ -64,7 +67,7 @@ import uuidimport yamlfrom fastapi import BackgroundTasks, FastAPI, HTTPException, Request, Response-from fastapi.responses import FileResponse+from fastapi.responses import FileResponse, JSONResponsefrom pydantic import BaseModelapp = FastAPI(title="harness-runner")@@ -82,6 +85,38 @@ _SID_SAFE = re.compile(r"[^A-Za-z0-9._-]")# session isolation. See _ws() and _reap_workspaces()._SANDBOX_PER_SESSION = os.environ.get("HR_SANDBOX_PER_SESSION", "").strip().lower() in ("1", "true", "on")+# THE SESSION WRITE-WALL, the second deployment invariant, declared by the self-hosted entrypoint+# (HR_SESSION_UIDS=1). One runner serves every session there, so "the session workspace" cannot be+# a sandbox boundary the way it is on a per-session sandbox; it has to be a permission boundary.+# The runner runs as root and every process that acts for a session (the agent CLI, its sidecar,+# git, tar) runs as that session's OWN uid, which owns its session directory and nothing else:+# the workspace root, the data volume, the product's processes and the shared scratch directories+# belong to other uids. A deliverable written to "/tmp/X", to the workspace parent or into another+# session's directory is then not lost and not stolen: it fails with EACCES at the write, the one+# moment the model is still there to pick the right path. Not an instruction (2026-08-21: an+# instruction binds only models that follow instructions), not a post-hoc adoption pass (on a shared+# root a stray file's name, content and mtime are attacker-controlled). A path the process cannot+# materialise is a path it cannot use.+#+# Mutually exclusive with the per-session sandbox: there the root IS the workspace and one uid is+# correct. Fails CLOSED: declared but not root means the wall cannot be built, and the runner+# refuses to start rather than quietly sharing one uid across sessions.+_SESSION_UIDS = os.environ.get("HR_SESSION_UIDS", "").strip().lower() in ("1", "true", "on")+_SESSION_UID_BASE = int(os.environ.get("HR_SESSION_UID_BASE", "20000") or 20000)+_SESSION_UID_SPAN = 40000+if _SESSION_UIDS and _SANDBOX_PER_SESSION:+ raise RuntimeError("HR_SESSION_UIDS and HR_SANDBOX_PER_SESSION are mutually exclusive: "+ "a per-session sandbox needs no per-session uid")+if _SESSION_UIDS and os.geteuid() != 0:+ raise RuntimeError("HR_SESSION_UIDS=1 requires the runner to run as root (it switches to a "+ "per-session uid for every agent process); refusing to start on a shared uid")+# Names an agent process must never inherit from the runner's environment. The turn sets the+# credential it needs explicitly (see turn()); everything else secret-shaped is the product's.+_SECRET_ENV = re.compile(r"^(HARNESS_INTERNAL_KEY|HR_AUTH_.*|HR_SECRET_KEY|HR_SESSION_KEY|HR_POOL_.*)$"+ r"|_API_KEY$|_SECRET(_|$)|_TOKEN$|PASSWORD", re.I)+_INTERNAL_KEY = os.environ.get("HARNESS_INTERNAL_KEY", "")+_uid_lock = threading.Lock()+# How long an untouched session workspace is kept. Sessions are resumable from their checkpoint,# so a reaped directory costs a rehydrate, not the work — but keeping every one forever fills the# disk of a box nobody is watching. 0 disables.@@ -152,6 +187,113 @@ def _ws(identifier: str = "") -> str:return WORKSPACE_ROOTsid = _SID_SAFE.sub("_", (identifier or "").strip())[:120] or "_default"return os.path.join(WORKSPACE_ROOT, sid)+def _session_uid(ws: str) -> int | None:+ """The uid this session's processes run as, or None when the write-wall is off or the+ directory has not been isolated yet. The directory's owner IS the record: nothing to keep in+ sync, and it survives a restart because ownership lives on the volume."""+ if not _SESSION_UIDS:+ return None+ try:+ uid = os.stat(ws).st_uid+ except OSError:+ return None+ return uid if _SESSION_UID_BASE <= uid < _SESSION_UID_BASE + _SESSION_UID_SPAN else None+++def _as_session(ws: str) -> dict:+ """Popen/run keyword arguments that make a child act as this session. Empty when the wall is+ off, so every spawn site reads the same with or without it."""+ uid = _session_uid(ws)+ return {"user": uid, "group": uid, "extra_groups": []} if uid is not None else {}+++def _ensure_passwd(uid: int, home: str) -> None:+ """A passwd entry for the session uid. The CLIs run without one (verified: all five start as+ an unlisted uid), but os.userInfo()-style lookups throw, and the entry costs nothing."""+ try:+ pwd.getpwuid(uid)+ return+ except KeyError:+ pass+ name = f"hs{uid}"+ try:+ subprocess.run(["groupadd", "-g", str(uid), name], capture_output=True)+ subprocess.run(["useradd", "-M", "-u", str(uid), "-g", str(uid), "-s", "/bin/bash",+ "-d", home, name], capture_output=True)+ except OSError:+ pass+++def _own_tree(root: str, uid: int, from_uids: set[int]) -> None:+ """chown everything under root that currently belongs to one of from_uids. Only those: a+ session can plant a hard link to a file it does not own, and chowning by position rather+ than by current owner would hand it that file. Symlinks are re-owned as links, never+ followed."""+ for dirpath, dirnames, filenames in os.walk(root):+ for name in dirnames + filenames:+ path = os.path.join(dirpath, name)+ try:+ st = os.lstat(path)+ if st.st_uid in from_uids and not (stat.S_ISREG(st.st_mode) and st.st_nlink > 1):+ os.lchown(path, uid, uid)+ except OSError:+ continue+++def _isolate_session(ws: str) -> None:+ """Make the session directory the one place its uid can write, and make everything in it+ that uid's. Allocation happens once, under a lock, from the owners of the directories that+ exist: a uid is free when no session directory carries it, so two sessions can never share+ one, and a reaped directory returns its uid. Every call after that re-owns what the runner+ wrote into the directory as root since the last one (agent doc, skills, input files, MCP+ configuration, the restored checkpoint)."""+ if not _SESSION_UIDS:+ return+ uid = _session_uid(ws)+ previous: set[int] = {0}+ if uid is None:+ with _uid_lock:+ uid = _session_uid(ws)+ if uid is None:+ used: set[int] = set()+ try:+ for e in os.scandir(WORKSPACE_ROOT):+ try:+ if e.is_dir(follow_symlinks=False):+ used.add(e.stat(follow_symlinks=False).st_uid)+ except OSError:+ continue+ except OSError:+ pass+ uid = next((u for u in range(_SESSION_UID_BASE, _SESSION_UID_BASE + _SESSION_UID_SPAN)+ if u not in used), None)+ if uid is None:+ raise HTTPException(503, "no free session uid")+ previous.add(os.stat(ws).st_uid) # a legacy directory: re-own its files too+ _ensure_passwd(uid, os.path.join(ws, HARNESS_STATE, "home"))+ os.chown(ws, uid, uid)+ os.chmod(ws, 0o700)+ _own_tree(ws, uid, previous)+++def _child_env() -> dict:+ """The environment an agent process starts from: the runner's, minus anything secret-shaped.+ On the self-hosted box the runner's environment is the container's, and that carried the+ console password, the internal key and the secret-store key into every agent process."""+ return {k: v for k, v in os.environ.items() if not _SECRET_ENV.search(k)}++[email protected]("http")+async def _internal_callers_only(request: Request, call_next):+ """Behind the write-wall the runner is reachable from every agent process on loopback, and its+ routes address any session by identifier. The gateway presents the internal key (which+ _child_env strips from agent processes); nothing else may drive this API."""+ if _SESSION_UIDS and _INTERNAL_KEY and request.url.path != "/healthz":+ if not hmac.compare_digest(request.headers.get("x-harness-internal", ""), _INTERNAL_KEY):+ return JSONResponse({"error": "internal key required"}, status_code=401)+ return await call_next(request)++# Where checkpoint/hydrate tarballs spool to disk (HR-INF-015 — never a RAM buffer). MUST be# OUTSIDE the workspace (so a leftover temp file can never be caught by a later `git add -A` or# re-tarred) AND on a real DISK, not a RAM-backed tmpfs (which would defeat the memory saving).@@ -259,7 +401,7 @@ def _start_sidecar(sid: str, collab_url: str, room: str, token: str = "") -> Non"BLACKBOARD_FILE": file, "COLLAB_TOKEN": token or ""}logf = open(os.path.join(ws, HARNESS_STATE, "sidecar.log"), "ab") # diagnosticsentry.update(proc=subprocess.Popen(["node", _SIDECAR_JS], cwd=ws, env=env,- stdout=logf, stderr=logf),+ stdout=logf, stderr=logf, **_as_session(ws)),room=room, error=None)except Exception as e: # noqa: BLE001entry.update(proc=None, room=None, error=str(e)[:200])@@ -281,7 +423,7 @@ def _ver(cmd: list[str]) -> str:# ── git-backed workspace (hydrate at turn start, checkpoint at turn end) ───────────def _git(ws: str, *args: str, check: bool = False) -> subprocess.CompletedProcess:return subprocess.run(["git", "-C", ws, *args], capture_output=True, text=True,- env={**os.environ, **_GIT_ENV}, check=check)+ env={**os.environ, **_GIT_ENV}, check=check, **_as_session(ws))def _git_ensure(ws: str) -> None:@@ -1849,7 +1991,7 @@ def _run_turn_bg(turn_id: str, cmd: list[str], env: dict, cwd: str, normalize, m# shell children (see _kill_proc_tree) instead of orphaning a pipe-holding child.proc = subprocess.Popen(cmd, cwd=cwd, env=env, text=True, bufsize=1,stdout=subprocess.PIPE, stderr=subprocess.STDOUT,- start_new_session=True)+ start_new_session=True, **_as_session(cwd))except Exception as e: # noqa: BLE001rec.update(status="failed", error=f"spawn: {e}"[:500], done=True)return@@ -1930,7 +2072,7 @@ def _run_codex_appserver_bg(turn_id: str, cwd: str, env: dict, model: str, promptry:proc = subprocess.Popen(["codex", "app-server"], cwd=cwd, env=env, text=True, bufsize=1,stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,- start_new_session=True)+ start_new_session=True, **_as_session(cwd))except Exception as e: # noqa: BLE001rec.update(status="failed", error=f"spawn app-server: {e}"[:500], done=True)return@@ -2219,7 +2361,7 @@ def _run_hermes_bg(turn_id: str, cwd: str, env: dict, model: str, provider: str,try:proc = subprocess.Popen(cmd, cwd=cwd, env=env, text=True, bufsize=1,stdout=subprocess.PIPE, stderr=subprocess.PIPE,- start_new_session=True)+ start_new_session=True, **_as_session(cwd))except Exception as e: # noqa: BLE001rec.update(status="failed", error=f"spawn: {e}"[:500], done=True)return@@ -2415,6 +2557,7 @@ async def hydrate(request: Request, identifier: str = "") -> dict:ws = _ws(identifier)ws_path = pathlib.Path(ws)ws_path.mkdir(parents=True, exist_ok=True)+ _isolate_session(ws)fd, spool_path = tempfile.mkstemp(suffix=".tgz", dir=SPOOL_DIR) # OUTSIDE the workspaceh = hashlib.sha256()nbytes = 0@@ -2461,7 +2604,8 @@ async def hydrate(request: Request, identifier: str = "") -> dict:restored = Falseif nbytes:with open(spool_path, "rb") as tar_in:- proc = subprocess.run(["tar", "xzf", "-", "-C", ws], stdin=tar_in, capture_output=True)+ proc = subprocess.run(["tar", "xzf", "-", "-C", ws], stdin=tar_in, capture_output=True,+ **_as_session(ws))if proc.returncode != 0:raise HTTPException(500, f"untar failed: {proc.stderr.decode(errors='replace')[:300]}")restored = True@@ -2562,6 +2706,47 @@ def get_file(path: str, identifier: str = "") -> Response:return Response(content=dest.read_bytes(), media_type=media)[email protected]("/file")+async def put_file(request: Request, path: str, identifier: str = "") -> dict:+ """Write ONE file into a session's workspace, as that session.++ The runner is the only process that acts for a session, and behind the write-wall it is the+ only one that CAN: the session directory belongs to the session's own uid, so the product+ cannot reach into it (that is the point). A live app writing a file into a workspace comes+ through here instead. Written beside and renamed, so a reader mid-turn sees the old file or+ the new one, never a half-written one."""+ ws = _ws(identifier)+ dest = _safe_join(ws, path)+ if dest is None:+ raise HTTPException(400, "path escapes the workspace")+ data = await request.body()+ pathlib.Path(ws).mkdir(parents=True, exist_ok=True)+ _isolate_session(ws)+ uid = _session_uid(ws)+ missing: list[pathlib.Path] = []+ probe = dest.parent+ while not probe.exists():+ missing.append(probe)+ probe = probe.parent+ dest.parent.mkdir(parents=True, exist_ok=True)+ tmp = dest.parent / f".hr-put-{uuid.uuid4().hex[:8]}"+ try:+ tmp.write_bytes(data)+ os.chmod(tmp, 0o644)+ if uid is not None:+ for d in missing:+ os.chown(d, uid, uid)+ os.chown(tmp, uid, uid)+ os.replace(tmp, dest)+ except OSError as e:+ try:+ tmp.unlink()+ except OSError:+ pass+ raise HTTPException(500, f"write failed: {str(e)[:200]}")+ return {"ok": True, "path": str(dest.relative_to(ws)), "bytes": len(data)}++@app.get("/capabilities")def capabilities(identifier: str = "") -> dict:_wsdir = _ws(identifier)@@ -2624,6 +2809,10 @@ def turn(req: TurnReq, identifier: str = "") -> dict:if not spec:raise HTTPException(400, f"unknown backend '{backend}' (one of {sorted(BACKENDS)})")cwd = req.cwd or _ws(identifier)+ if _SESSION_UIDS and req.cwd and os.path.realpath(req.cwd) != os.path.realpath(_ws(identifier)):+ # Behind the wall the directory decides which uid a turn runs as; a caller-chosen one+ # would be a turn in another session's identity.+ raise HTTPException(400, "cwd is decided by the session identifier")os.makedirs(cwd, exist_ok=True)_write_input_files(cwd, req.files) # land caller-attached files in the workspace pre-run# Built-in skills the harness disabled must NOT be mounted. On BusinessOS built-ins aren't@@ -2654,7 +2843,7 @@ def turn(req: TurnReq, identifier: str = "") -> dict:agent_doc = ((agent_doc + "\n\n") if agent_doc.strip() else "") + \f"## Disabled tools\n\nDo NOT use these tools — they are disabled for this harness: {_off}."_write_agent_doc(cwd, backend, agent_doc, installed_skills)- env = os.environ.copy()+ env = _child_env()# Image generation. Deliberately NOT the OPENAI_* names: on a codex harness those already# point at the CHAT connection, which is often a different provider, and one env pair can# only carry one credential. The imagegen skill's wrapper reads these and passes them to the@@ -2674,6 +2863,13 @@ def turn(req: TurnReq, identifier: str = "") -> dict:home = os.path.join(cwd, ".harness", "home")os.makedirs(home, exist_ok=True)env["HOME"] = home+ if _SESSION_UIDS:+ # The shared scratch directories are closed to session uids, so the session's own scratch+ # (checkpoint- and collection-excluded by design) is what tempfile, os.tmpdir() and the+ # CLIs' temp files use.+ scratch = os.path.join(cwd, "tmp")+ os.makedirs(scratch, exist_ok=True)+ env["TMPDIR"] = env["TMP"] = env["TEMP"] = scratchauth = req.auth or Auth()model = req.model or spec["default_model"]use_appserver = backend == "codex" and bool(req.codex_appserver)@@ -2708,6 +2904,7 @@ def turn(req: TurnReq, identifier: str = "") -> dict:cmd = _build_claude(req.provider, auth, model, req.prompt, req.max_turns, cwd, env,resume_session_id=req.resume_session_id, mcp_config=mcp_config,disallowed_tools=req.tools_disabled, partial=bool(req.partial_messages))+ _isolate_session(cwd) # everything the runner just wrote into the session is the session's nowturn_id = "turn" + uuid.uuid4().hexwith _turns_lock:# Double-check under the lock: a concurrent retry with the same key may have raced past thediff --git a/runner/tests/test_session_uids.py b/runner/tests/test_session_uids.pynew file mode 100644index 00000000..b7496799--- /dev/null+++ b/runner/tests/test_session_uids.py@@ -0,0 +1,99 @@+"""The session write-wall (HR_SESSION_UIDS): what it changes when declared, and that it changes+nothing when it is not. The uid switch itself needs root and is exercised live on a self-hosted+box; these pin the parts a test process can reach."""+import os+import sys+from pathlib import Path++import pytest+from fastapi.testclient import TestClient++sys.path.insert(0, str(Path(__file__).resolve().parents[1]))+import server # noqa: E402+++def test_wall_off_changes_nothing(tmp_path, monkeypatch):+ monkeypatch.setattr(server, "_SESSION_UIDS", False)+ ws = tmp_path / "s1"+ ws.mkdir()+ assert server._session_uid(str(ws)) is None+ assert server._as_session(str(ws)) == {}+ server._isolate_session(str(ws)) # a no-op, not an error, on a non-root test process+ assert (ws.stat().st_mode & 0o777) == 0o755 or (ws.stat().st_mode & 0o777) == 0o775+++def test_session_uid_reads_the_directory_owner(tmp_path, monkeypatch):+ monkeypatch.setattr(server, "_SESSION_UIDS", True)+ ws = tmp_path / "s2"+ ws.mkdir()+ # Owned by the test user: outside the session range, so "not isolated yet".+ assert server._session_uid(str(ws)) is None+ assert server._as_session(str(ws)) == {}+ fake = server._SESSION_UID_BASE + 7+ real_stat = os.stat++ class St:+ st_uid = fake++ monkeypatch.setattr(server.os, "stat", lambda p, *a, **k: St() if str(p) == str(ws) else real_stat(p, *a, **k))+ assert server._session_uid(str(ws)) == fake+ assert server._as_session(str(ws)) == {"user": fake, "group": fake, "extra_groups": []}++[email protected]("name,stripped", [+ ("HARNESS_INTERNAL_KEY", True), ("HR_AUTH_PASSWORD", True), ("HR_AUTH_USER", True),+ ("HR_SECRET_KEY", True), ("HR_SESSION_KEY", True), ("OPENAI_API_KEY", True),+ ("AWS_SECRET_ACCESS_KEY", True), ("GITHUB_TOKEN", True), ("DB_PASSWORD", True),+ ("PATH", False), ("HOME", False), ("HR_DSH_PYTHON", False), ("HR_PI_MCP_EXT", False),+ ("NODE_PATH", False), ("HERMES_DISABLE_LAZY_INSTALLS", False), ("OFFICECLI_RESIDENT_FLUSH", False),+ ("HARNESS_WORKSPACE", False), ("HR_BACKENDS", False),+])+def test_child_env_strips_secrets_and_keeps_the_runtime(monkeypatch, name, stripped):+ monkeypatch.setenv(name, "v")+ assert (name not in server._child_env()) is stripped+++def test_own_tree_only_reowns_the_listed_owners_and_never_hard_links(tmp_path, monkeypatch):+ root = tmp_path / "ws"+ (root / "sub").mkdir(parents=True)+ (root / "a.txt").write_text("a")+ (root / "sub" / "b.txt").write_text("b")+ (root / "planted").write_text("x")+ os.link(root / "planted", root / "link2") # nlink == 2 on both names+ os.symlink("/etc/hostname", root / "sym")+ calls: list[tuple[str, int, int]] = []+ monkeypatch.setattr(server.os, "lchown", lambda p, u, g: calls.append((os.path.basename(p), u, g)))+ me = os.getuid()+ server._own_tree(str(root), 31337, {me})+ names = {c[0] for c in calls}+ assert {"sub", "a.txt", "b.txt", "sym"} <= names+ assert "planted" not in names and "link2" not in names+ assert all(u == 31337 and g == 31337 for _, u, g in calls)+ calls.clear()+ server._own_tree(str(root), 31337, {0}) # nothing here is root's: nothing moves+ assert calls == []+++def test_runner_api_requires_the_internal_key_behind_the_wall(monkeypatch):+ monkeypatch.setattr(server, "_SESSION_UIDS", True)+ monkeypatch.setattr(server, "_INTERNAL_KEY", "k-test")+ c = TestClient(server.app)+ assert c.get("/healthz").status_code == 200+ assert c.get("/backends").status_code == 401+ assert c.get("/backends", headers={"x-harness-internal": "wrong"}).status_code == 401+ assert c.get("/backends", headers={"x-harness-internal": "k-test"}).status_code == 200+++def test_runner_api_is_open_when_the_wall_is_off(monkeypatch):+ monkeypatch.setattr(server, "_SESSION_UIDS", False)+ monkeypatch.setattr(server, "_INTERNAL_KEY", "k-test")+ assert TestClient(server.app).get("/backends").status_code == 200+++def test_turn_refuses_a_caller_chosen_cwd_behind_the_wall(monkeypatch, tmp_path):+ monkeypatch.setattr(server, "_SESSION_UIDS", True)+ monkeypatch.setattr(server, "_INTERNAL_KEY", "")+ c = TestClient(server.app)+ r = c.post("/turn?identifier=sA", json={"prompt": "x", "backend": "claude", "cwd": str(tmp_path)})+ assert r.status_code == 400+ assert "identifier" in r.text