refactor(server): run agent runtime on Node 24

Author: FelixTJDietrich

.changeset/modern-node-agent-runtime.md

@@ -0,0 +1,7 @@
+---
+"hephaestus": minor
+---
+
+Run sandboxed practice reviews and mentor sessions on Node.js 24 with a 256 MB JavaScript heap ceiling and scoped runner filesystem permissions.
+
+**Operators:** Upgrade the agent image and server together. Runtime contract v2 reports a mismatched image as unsupported; follow the coordinated upgrade steps in `MIGRATION.md`.

.github/workflows/ci-quality-gates.yml

@@ -79,6 +79,12 @@ jobs:
         if: steps.should_run.outputs.run == 'true'
         uses: ./.github/actions/setup-bun
 
+      - name: Setup agent Node runtime
+        if: steps.should_run.outputs.run == 'true' && matrix.check == 'application-server-quality'
+        uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
+        with:
+          node-version: 24.19.0
+
       - name: Setup caches
         if: steps.should_run.outputs.run == 'true'
         uses: ./.github/actions/setup-caches

.github/workflows/release.yml

@@ -217,7 +217,7 @@ jobs:
           set -euo pipefail
           docker pull "$IMAGE"
           docker run --rm --entrypoint /bin/sh "$IMAGE" -c \
-            'bun --version && ! command -v node >/dev/null 2>&1'
+            'node --version && for runtime in bun npm npx corepack yarn yarnpkg pnpm pnpx; do ! command -v "$runtime"; done'
 
           expected=$(grep -oE 'RUNTIME_CONTRACT_VERSION = [0-9]+' "$LAYOUT" | grep -oE '[0-9]+$')
           [ -n "$expected" ] || { echo "::error::Could not read RUNTIME_CONTRACT_VERSION from $LAYOUT"; exit 1; }

MIGRATION.md

@@ -63,6 +63,22 @@ Before upgrading to any new `0.x.0` version:
 Entries exist only for releases that need operator action. Everything else is in the
 [release notes](https://github.com/ls1intum/Hephaestus/releases).
 
+### v0.76.0
+
+#### 🔴 Upgrade the server and agent image together
+
+**Affected**: every deployment that runs practice reviews or mentor sessions.
+
+**Before**: runtime contract v1 executes staged TypeScript with Bun.
+
+**After**: runtime contract v2 executes it with Node.js 24, a 256 MB V8 heap ceiling, and scoped
+runner filesystem permissions. The server reports an image with a different contract as unsupported before sandbox work
+starts.
+
+**Migration**: deploy the application server/worker and the matching `hephaestus-agent` image from the
+same release. Do not reuse or independently pin an older agent image. After deployment, verify the agent
+image reports `hephaestus.agent.runtime-contract=2`, contains Node 24, and does not contain Bun.
+
 ### v0.75.0
 
 #### 🔴 Practice reviews now require the person being evaluated to be a workspace member

bunfig.toml

@@ -4,6 +4,3 @@ hoist = false
 publicHoistPattern = ["react", "react-dom", "@types/react", "@types/react-dom", "@types/hast"]
 minimumReleaseAge = 259200
 peer = true
-
-[run]
-bun = true

docker/agents/pi/Dockerfile

@@ -1,57 +1,38 @@
 # syntax=docker/dockerfile:1.4
-ARG DEBIAN_TAG=bookworm-slim
-FROM debian:${DEBIAN_TAG}
+# renovate: datasource=docker depName=node
+ARG NODE_VERSION=24.19.0
+FROM node:${NODE_VERSION}-slim@sha256:a9f5f7c91a432850b2a8a7797adf5eadb6c733ceed61167806cee7ea7fbc29df
 
-ARG TARGETARCH
-
-RUN apt-get update -qq && apt-get install -y --no-install-recommends git findutils tree jq curl ca-certificates unzip && \
+RUN apt-get update -qq && apt-get install -y --no-install-recommends git findutils tree jq ca-certificates grep && \
     rm -rf /var/lib/apt/lists/*
 
-# Refresh the release-asset hashes from SHASUMS256.txt with every version bump.
-# renovate: datasource=github-releases depName=oven-sh/bun extractVersion=^bun-v(?<version>.*)$
-ARG BUN_VERSION=1.4.0
-RUN arch="${TARGETARCH:-$(dpkg --print-architecture)}" && \
-    case "${arch}" in \
-        amd64|x86_64) bun_arch="x64"; bun_sha256="2d03fb5fb83ac8b567aca0a281b2ce1a1a19d488f56c2968d88c3f25e92fe452" ;; \
-        arm64|aarch64) bun_arch="aarch64"; bun_sha256="4b1a332ee861983eb93bcfe6f770fff94e3e31b2c388bdaea3c8ed35e58eed0e" ;; \
-        *) echo "Unsupported TARGETARCH/architecture: ${arch}" >&2; exit 1 ;; \
-    esac && \
-    curl --fail --show-error --silent --location --retry 3 --retry-delay 2 \
-        "https://github.com/oven-sh/bun/releases/download/bun-v${BUN_VERSION}/bun-linux-${bun_arch}.zip" \
-        -o /tmp/bun.zip && \
-    echo "${bun_sha256}  /tmp/bun.zip" | sha256sum -c - && \
-    unzip -o /tmp/bun.zip -d /tmp && \
-    mv "/tmp/bun-linux-${bun_arch}/bun" /usr/local/bin/bun && \
-    chmod +x /usr/local/bin/bun && \
-    rm -rf /tmp/bun*
-
-# Provide a resolvable non-root home and passwd entry.
-RUN groupadd --gid 1000 agent && \
-    useradd --uid 1000 --gid 1000 --home-dir /home/agent --create-home --shell /bin/bash agent
+RUN groupmod --new-name agent node && \
+    usermod --login agent --home /home/agent --move-home --shell /bin/bash node
 
 # renovate: datasource=npm depName=@earendil-works/pi-coding-agent
 ARG PI_VERSION=0.84.3
 RUN mkdir -p /opt/pi-sdk && cd /opt/pi-sdk && \
     printf '{"name":"hephaestus-pi-sdk","private":true,"dependencies":{"@earendil-works/pi-coding-agent":"%s"}}\n' \
         "${PI_VERSION}" > package.json && \
-    BUN_INSTALL_CACHE_DIR=/tmp/bun-cache bun install --production --ignore-scripts --no-progress && \
-    rm -rf /tmp/bun-cache && \
+    npm install --omit=dev --ignore-scripts --no-audit --no-fund && \
     test -d /opt/pi-sdk/node_modules/@earendil-works/pi-coding-agent \
       || (echo "Pi SDK not found at /opt/pi-sdk/node_modules" >&2; exit 1) && \
     chown -R 1000:1000 /opt/pi-sdk && \
     mkdir -p /workspace && chown 1000:1000 /workspace
 
-# Resolve the SDK through the same workspace symlink used at runtime.
 RUN mkdir -p /tmp/abi-check && ln -sf /opt/pi-sdk/node_modules /tmp/abi-check/node_modules && \
     cd /tmp/abi-check && \
     printf 'const sdk = await import("@earendil-works/pi-coding-agent");\nif (!sdk || typeof sdk !== "object") { throw new Error("Pi SDK import yielded no module namespace"); }\nconsole.log("pi sdk exports:", Object.keys(sdk).length);\n' > check.ts && \
-    bun check.ts && \
+    node --permission --allow-fs-read=/tmp/abi-check --allow-fs-read=/opt/pi-sdk check.ts && \
+    ! node --permission --allow-fs-read=/tmp/abi-check --allow-fs-read=/opt/pi-sdk \
+      -e 'require("node:fs").readFileSync("/etc/passwd")' 2>/dev/null && \
+    ! node --permission --allow-fs-read=/tmp/abi-check --allow-fs-read=/opt/pi-sdk \
+      -e 'require("node:child_process").spawnSync("true")' 2>/dev/null && \
     rm -rf /tmp/abi-check
 
 COPY --chown=1000:1000 precompute/runner.ts /opt/precompute/runner.ts
 COPY --chown=1000:1000 precompute/lib/ /opt/precompute/lib/
 
-# Neutralize git hooks/external-command vectors (DockerSandboxAdapter re-enforces at runtime).
 RUN git config --system core.hooksPath /nonexistent && \
     git config --system core.fsmonitor false && \
     git config --system safe.directory /workspace/repo
@@ -61,28 +42,23 @@ ENV GIT_PAGER=cat
 ENV GIT_TERMINAL_PROMPT=0
 ENV LANG=C.UTF-8
 
-# Check both PATH and standard binary directories after all installation layers.
-RUN set -eu; \
-    for b in node nodejs npm npx corepack yarn pnpm; do \
-        if command -v "$b" >/dev/null 2>&1; then \
-            echo "FATAL: '$b' resolves to $(command -v "$b") — this image must be Bun-only." >&2; exit 1; \
-        fi; \
-    done; \
-    found="$(find /usr/bin /usr/local/bin /bin /sbin /usr/sbin /opt -maxdepth 3 \
-        \( -name node -o -name nodejs -o -name npm -o -name npx -o -name corepack \) \
+RUN rm -rf /usr/local/lib/node_modules/npm /usr/local/lib/node_modules/corepack \
+        /usr/local/bin/npm /usr/local/bin/npx /usr/local/bin/corepack \
+        /usr/local/bin/yarn /usr/local/bin/yarnpkg /usr/local/bin/pnpm /usr/local/bin/pnpx && \
+    set -eu; \
+    if command -v bun >/dev/null 2>&1; then \
+        echo "FATAL: Bun resolves to $(command -v bun); this image must be Node-only." >&2; exit 1; \
+    fi; \
+    found="$(find /usr/bin /usr/local/bin /bin /sbin /usr/sbin /opt -maxdepth 3 -name bun \
         \( -type f -o -type l \) 2>/dev/null || true)"; \
     if [ -n "$found" ]; then \
-        echo "FATAL: Node.js artefacts present in the image:" >&2; echo "$found" >&2; exit 1; \
+        echo "FATAL: Bun artefacts present in the image:" >&2; echo "$found" >&2; exit 1; \
     fi; \
-    echo "OK: no node/npm in image; runtime is $(bun --version) at $(command -v bun)"
+    node --version; \
+    for manager in npm npx corepack yarn yarnpkg pnpm pnpx; do ! command -v "$manager"; done
 
-# The build above proves the runtime contract — Bun resolves and imports the SDK exactly as
-# PiRuntimeFactory arranges it, and no Node survives. These labels are the only part of that proof a
-# server can read before it commits a job to a container: it compares the contract version against
-# SandboxLayout.RUNTIME_CONTRACT_VERSION, which AgentImageContractSyncTest pins to the line below.
-# Bump both together when an older image could no longer run the staged runners. ADR 0031.
-LABEL hephaestus.agent.runtime-contract=1
-LABEL hephaestus.agent.bun-version=${BUN_VERSION}
+LABEL hephaestus.agent.runtime-contract=2
+LABEL hephaestus.agent.node-version=${NODE_VERSION}
 LABEL hephaestus.agent.pi-version=${PI_VERSION}
 
 USER 1000:1000

docker/agents/precompute/lib/context.ts

@@ -10,7 +10,9 @@
  * they never decide.
  */
 
-import { isJsonObject } from "./practice-contract";
+import { readFile } from "node:fs/promises";
+
+import { isJsonObject } from "./practice-contract.ts";
 
 /**
  * Best-effort JSON read of a context file; returns `null` when absent/unreadable (the common case).
@@ -25,9 +27,7 @@ export async function readContextJson(
 ): Promise<unknown> {
 	if (!contextDir) return null;
 	try {
-		const file = Bun.file(`${contextDir}/${name}`);
-		if (!(await file.exists())) return null;
-		return await file.json();
+		return JSON.parse(await readFile(`${contextDir}/${name}`, "utf8"));
 	} catch {
 		return null;
 	}

docker/agents/precompute/lib/diff-parser.ts

@@ -1,4 +1,4 @@
-import type { DiffFile, DiffHunk } from "./types";
+import type { DiffFile, DiffHunk } from "./types.ts";
 
 /**
  * Parse a unified diff (with optional [L<n>] annotations) into structured DiffFile objects.

docker/agents/precompute/lib/files.ts

@@ -0,0 +1,10 @@
+import { globSync } from "node:fs";
+import { join, relative } from "node:path";
+
+/** Return matching files in stable order. */
+export function globFilesSync(pattern: string, cwd: string): string[] {
+	return globSync(pattern, { cwd, withFileTypes: true })
+		.filter((entry) => entry.isFile())
+		.map((entry) => relative(cwd, join(entry.parentPath, entry.name)))
+		.toSorted();
+}

docker/agents/precompute/lib/grep.test.ts

@@ -1,9 +1,11 @@
-import { afterEach, describe, expect, it } from "bun:test";
-import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { afterEach, describe, it } from "node:test";
 
-import { findFiles, grep } from "./grep";
+import { globFilesSync } from "./files.ts";
+import { findFiles, grep } from "./grep.ts";
 
 const tempDirs: string[] = [];
 
@@ -17,12 +19,12 @@ afterEach(async () => {
 	await Promise.all(tempDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
 });
 
-describe("grep", () => {
-	it("treats fixed-string patterns literally without shell interpretation", async () => {
+void describe("grep", () => {
+	void it("treats fixed-string patterns literally without shell interpretation", async () => {
 		const dir = await createTempDir();
 		const nestedDir = join(dir, "nested dir");
 		await mkdir(nestedDir, { recursive: true });
-		await Bun.write(
+		await writeFile(
 			join(nestedDir, "example.ts"),
 			"const marker = \"literal $(echo nope) 'quotes'\";\n",
 		);
@@ -32,73 +34,84 @@ describe("grep", () => {
 			glob: "**/*.ts",
 		});
 
-		expect(matches).toHaveLength(1);
-		expect(matches[0]?.file).toBe("nested dir/example.ts");
+		assert.equal(matches.length, 1);
+		assert.equal(matches[0]?.file, "nested dir/example.ts");
 	});
 
-	it("enforces maxResults globally across files", async () => {
+	void it("enforces maxResults globally across files", async () => {
 		const dir = await createTempDir();
-		await Bun.write(join(dir, "one.txt"), "needle\nneedle\n");
-		await Bun.write(join(dir, "two.txt"), "needle\nneedle\n");
-		await Bun.write(join(dir, "three.txt"), "needle\nneedle\n");
+		await writeFile(join(dir, "one.txt"), "needle\nneedle\n");
+		await writeFile(join(dir, "two.txt"), "needle\nneedle\n");
+		await writeFile(join(dir, "three.txt"), "needle\nneedle\n");
 
 		const matches = await grep("needle", dir, {
 			fixedString: true,
 			maxResults: 2,
 		});
 
-		expect(matches).toHaveLength(2);
-		expect(matches.every((match) => match.content === "needle")).toBe(true);
+		assert.equal(matches.length, 2);
+		assert.equal(
+			matches.every((match) => match.content === "needle"),
+			true,
+		);
 	});
 
-	it("applies path-aware glob filters instead of basename-only includes", async () => {
+	void it("applies path-aware glob filters instead of basename-only includes", async () => {
 		const dir = await createTempDir();
 		const nestedDir = join(dir, "src", "nested");
 		await mkdir(nestedDir, { recursive: true });
-		await Bun.write(join(nestedDir, "match.ts"), "needle\n");
-		await Bun.write(join(nestedDir, "skip.js"), "needle\n");
+		await writeFile(join(nestedDir, "match.ts"), "needle\n");
+		await writeFile(join(nestedDir, "skip.js"), "needle\n");
 
 		const matches = await grep("needle", dir, {
 			fixedString: true,
 			glob: "src/**/*.ts",
 		});
 
-		expect(matches).toHaveLength(1);
-		expect(matches[0]?.file).toBe("src/nested/match.ts");
+		assert.equal(matches.length, 1);
+		assert.equal(matches[0]?.file, "src/nested/match.ts");
 	});
 
-	it("auto-expands basename-only globs to recursive matching", async () => {
+	void it("auto-expands basename-only globs to recursive matching", async () => {
 		const dir = await createTempDir();
 		await mkdir(join(dir, "src", "Views"), { recursive: true });
-		await Bun.write(join(dir, "src", "Views", "ContentView.swift"), 'print("hello")\n');
-		await Bun.write(join(dir, "RootFile.swift"), 'print("root")\n');
+		await writeFile(join(dir, "src", "Views", "ContentView.swift"), 'print("hello")\n');
+		await writeFile(join(dir, "RootFile.swift"), 'print("root")\n');
 
 		const matches = await grep("print", dir, {
 			fixedString: true,
 			glob: "*.swift",
 		});
 
-		expect(matches).toHaveLength(2);
+		assert.equal(matches.length, 2);
 		const files = matches.map((m) => m.file).toSorted();
-		expect(files).toContain("RootFile.swift");
-		expect(files).toContain("src/Views/ContentView.swift");
+		assert.ok(files.includes("RootFile.swift"));
+		assert.ok(files.includes("src/Views/ContentView.swift"));
 	});
 
-	it("finds extension matches without shelling out and skips ignored paths", async () => {
+	void it("finds extension matches without shelling out and skips ignored paths", async () => {
 		const dir = await createTempDir();
 		await mkdir(join(dir, "src", "nested"), { recursive: true });
 		await mkdir(join(dir, ".hidden"), { recursive: true });
 		await mkdir(join(dir, "node_modules", "pkg"), { recursive: true });
 		await mkdir(join(dir, ".build"), { recursive: true });
 
-		await Bun.write(join(dir, "src", "nested", "match.swift"), "struct Match {}\n");
-		await Bun.write(join(dir, ".hidden", "hidden.swift"), "struct Hidden {}\n");
-		await Bun.write(join(dir, "node_modules", "pkg", "dep.swift"), "struct Dep {}\n");
-		await Bun.write(join(dir, ".build", "generated.swift"), "struct Generated {}\n");
+		await writeFile(join(dir, "src", "nested", "match.swift"), "struct Match {}\n");
+		await writeFile(join(dir, ".hidden", "hidden.swift"), "struct Hidden {}\n");
+		await writeFile(join(dir, "node_modules", "pkg", "dep.swift"), "struct Dep {}\n");
+		await writeFile(join(dir, ".build", "generated.swift"), "struct Generated {}\n");
 
 		const files = findFiles(dir, "swift");
 
-		expect(files).toHaveLength(1);
-		expect(files[0]).toBe(join(dir, "src", "nested", "match.swift"));
+		assert.equal(files.length, 1);
+		assert.equal(files[0], join(dir, "src", "nested", "match.swift"));
+	});
+
+	void it("never returns a directory whose name matches the file pattern", async () => {
+		const dir = await createTempDir();
+		await mkdir(join(dir, "directory.ts"));
+		await writeFile(join(dir, "file.ts"), "export {};\n");
+
+		assert.deepEqual(globFilesSync("*.ts", dir), ["file.ts"]);
 	});
 });