pi-harness-runtime 1.1.394 → 1.1.396

package/packages/contracts/src/workspace-env-format.ts

@@ -90,6 +90,43 @@ export function isLauncherCommand(cmdline: string): boolean {
 	return /^(npm|bun|yarn|pnpm)\b.*\b(run\s+)?(dev|start)\b/.test(cmdline.trim());
 }
 
+/**
+ * The RAM rule behind the "low memory" warning.
+ *
+ * The warning exists to avoid running a build AND a dev server in parallel,
+ * so it is about the headroom that is actually available - not about the size
+ * of the machine. A 15 GB laptop with 6.5 GB free can build; a 32 GB server
+ * with 3 GB free cannot.
+ *
+ * - Below 4 GB free: always low.
+ * - Below 16 GB total: a small machine needs real headroom (6 GB) before a
+ *   parallel build and dev server are safe.
+ */
+export function isLowRamWarning(totalGb: number | null, availableGb: number | null): boolean {
+	if (availableGb === null) return false;
+	if (availableGb < 4) return true;
+	if (totalGb === null) return false;
+	return totalGb < 16 && availableGb < 6;
+}
+
+/**
+ * The headroom a build needs before it is allowed in development mode.
+ */
+export const MIN_BUILD_HEADROOM_GB = 2;
+
+/**
+ * The reason the build permission is (not) given.
+ *
+ * The agent has to know WHY a build is not allowed: an unknown environment
+ * needs an explicit request, a memory shortage needs a lighter build.
+ */
+export function buildAllowanceReason(env: WorkspaceEnvResult): string {
+	if (env.buildAllowed) return "yes";
+	if (env.mode === "unknown") return "no - requires explicit request";
+	if (env.lowRamWarning) return "no - low memory";
+	return "no - requires explicit request";
+}
+
 export type ServerState = "running" | "not-detected" | "not-checked";
 
 /**
@@ -231,6 +268,51 @@ export function isEnvShapedKey(key: string): boolean {
 	return /(^|_)(ENV|ENVIRONMENT|MODE|STAGE)$/i.test(key);
 }
 
+/**
+ * The namespaces of the desktop session variables.
+ *
+ * A session variable names the desktop session ("GNOME_SHELL_SESSION_MODE",
+ * "XDG_SESSION_TYPE"), never the environment of a workspace. Some of them
+ * end in "_MODE" or "_ENV", so without this list they look like an
+ * environment selector and decide the mode of a workspace that has no
+ * environment at all.
+ */
+const SESSION_VARIABLE_PREFIXES = [
+	"GNOME_",
+	"XDG_",
+	"DESKTOP_",
+	"DBUS_",
+	"GDM_",
+	"SDDM_",
+	"LIGHTDM_",
+	"GTK_",
+	"QT_",
+	"MATE_",
+	"KDE_",
+	"PLASMA_",
+	"UNITY_",
+	"XFCE_",
+	"CINNAMON_",
+	"WAYLAND_",
+	"MIR_",
+	"I3_",
+	"TERM_",
+	"SSH_",
+	"TMUX_",
+];
+
+/**
+ * True for a key that belongs to the desktop session, not to the workspace.
+ *
+ * The rule is a namespace list, not a value check: the value of a session
+ * variable ("ubuntu", "wayland", "user") says nothing about the environment
+ * of a workspace, so such a variable must never name the mode.
+ */
+export function isSessionVariableKey(key: string): boolean {
+	const upper = key.toUpperCase();
+	return SESSION_VARIABLE_PREFIXES.some((prefix) => upper.startsWith(prefix));
+}
+
 /**
  * True for a key that may hold a secret.
  */
@@ -282,6 +364,9 @@ export function detectModeHint(
 ): DotenvVar | null {
 	const nodeEnv = vars.find((v) => v.key === "NODE_ENV");
 	if (nodeEnv) return nodeEnv;
+	// A session variable is not an environment selector: it must never
+	// become the hint that names the mode.
+	const usableVars = vars.filter((v) => !isSessionVariableKey(v.key));
 	// The value match is opt-in: a caller that passes the process env
 	// variables must not let an unrelated variable that happens to hold the
 	// word "development" decide the mode.
@@ -289,7 +374,7 @@ export function detectModeHint(
 		// An environment shaped key whose value names a known mode wins: an
 		// earlier "APP_MODE=staging" or an empty "APP_ENV=" of the same file
 		// must not shadow the "AMOS_ENV=development" of the same file.
-		const usable = vars.find(
+		const usable = usableVars.find(
 			(v) =>
 				v.key !== "NODE_ENV" &&
 				isEnvShapedKey(v.key) &&
@@ -299,7 +384,9 @@ export function detectModeHint(
 	}
 	// No usable key: fall back to the first environment shaped key so that
 	// the label can name it (it names no known mode).
-	return vars.find((v) => v.key !== "NODE_ENV" && isEnvShapedKey(v.key)) ?? null;
+	return (
+		usableVars.find((v) => v.key !== "NODE_ENV" && isEnvShapedKey(v.key)) ?? null
+	);
 }
 
 /**
@@ -363,6 +450,9 @@ export function collectProcessEnvVars(env: NodeJS.ProcessEnv = process.env): Dot
 	for (const key of Object.keys(env)) {
 		const value = env[key];
 		if (value === undefined) continue;
+		// A session variable of the desktop is never an environment
+		// selector, so it is not even collected as a candidate.
+		if (isSessionVariableKey(key)) continue;
 		if (key === "NODE_ENV" || isEnvShapedKey(key)) {
 			vars.push({ key, value });
 		}
@@ -379,6 +469,98 @@ export interface ModeResolution {
 	source: "process.env" | ".env file" | null;
 }
 
+/**
+ * The deployment configuration of a repository.
+ *
+ * A repository that carries one of these files is deployed somewhere: it
+ * has a runtime environment of its own, so the shape of the repository
+ * cannot prove that the workspace is a development checkout.
+ */
+export const DEPLOYMENT_MARKER_FILES = [
+	"Dockerfile",
+	"Containerfile",
+	"docker-compose.yml",
+	"docker-compose.yaml",
+	"compose.yml",
+	"compose.yaml",
+	"Procfile",
+	"fly.toml",
+	"render.yaml",
+	"railway.json",
+	"vercel.json",
+	"netlify.toml",
+	"serverless.yml",
+	"serverless.yaml",
+	"app.yaml",
+	"ecosystem.config.cjs",
+	"ecosystem.config.js",
+] as const;
+
+/**
+ * The facts about the repository the workspace belongs to.
+ *
+ * They are read from the file system (and from git), never from a variable:
+ * a published package that is deployed nowhere is source code that the
+ * user runs on their own machine.
+ */
+export interface RepositoryFacts {
+	/** The workspace is a git checkout. */
+	isGitRepository: boolean;
+	/** The current branch ("" when it cannot be read). */
+	branch: string;
+	/** The package.json describes a package that is published to a registry. */
+	isPublishedPackage: boolean;
+	/** The repository carries a deployment configuration. */
+	hasDeploymentMarker: boolean;
+	/** A dev or build server runs in this workspace. */
+	hasRunningServer: boolean;
+}
+
+/**
+ * A mode that the facts about the repository named.
+ */
+export interface RepositoryModeDetection {
+	mode: WorkspaceMode;
+	/**
+	 * The phrase that names the detection.
+	 *
+	 * It is used as the key of the evidence ("source-only repository",
+	 * "git branch develop"), so the label can name it the same way it
+	 * names a variable.
+	 */
+	key: string;
+}
+
+/**
+ * The branches that name a development line of work.
+ */
+const DEVELOPMENT_BRANCHES = new Set(["develop", "development"]);
+
+/**
+ * Name the mode of a workspace from the facts about its repository.
+ *
+ * This is the LAST tier of the mode detection: it runs only when no
+ * variable names the environment at all. It never claims production - a
+ * checkout of a production branch is not a production environment, and the
+ * deployment marker of the repository keeps the answer honest.
+ *
+ * Two sets of facts name a development workspace:
+ * 1. a published package without a deployment configuration and without a
+ *    running server: source code that the user runs on their own machine
+ * 2. a branch that names a development line of work ("develop")
+ */
+export function modeFromRepositoryFacts(facts: RepositoryFacts): RepositoryModeDetection | null {
+	if (!facts.isGitRepository) return null;
+	if (facts.isPublishedPackage && !facts.hasDeploymentMarker && !facts.hasRunningServer) {
+		return { mode: "development", key: "source-only repository" };
+	}
+	const branch = facts.branch.trim().toLowerCase();
+	if (DEVELOPMENT_BRANCHES.has(branch)) {
+		return { mode: "development", key: `git branch ${branch}` };
+	}
+	return null;
+}
+
 /**
  * Resolve the workspace mode from the variables that were found.
  *
@@ -436,6 +618,17 @@ function findModeEvidence(env: WorkspaceEnvResult): EnvEvidence | undefined {
 	return candidates.find((e) => modeFromValue(e.value) !== null) ?? candidates[0];
 }
 
+/**
+ * The evidence entry that names the mode through the repository (if any).
+ *
+ * A detection is weaker than a variable: it is the shape of the checkout,
+ * not a declaration of the environment. It is therefore only used when no
+ * variable names the environment at all.
+ */
+function findDetectionEvidence(env: WorkspaceEnvResult): EnvEvidence | undefined {
+	return env.evidence.find((e) => e.source === "detection");
+}
+
 /**
  * Human readable mode label.
  *
@@ -451,9 +644,12 @@ export function describeWorkspaceMode(env: WorkspaceEnvResult): string {
 	const hint = findModeEvidence(env);
 	const where = hint?.file ? ` in ${hint.file}` : "";
 	if (env.mode !== "unknown") {
-		return hint
-			? `${env.mode.toUpperCase()} (from ${hint.key}${where})`
-			: env.mode.toUpperCase();
+		if (hint) return `${env.mode.toUpperCase()} (from ${hint.key}${where})`;
+		// The mode came from the repository, not from a variable: the label
+		// names the reason ("DEVELOPMENT (source-only repository)").
+		const detection = findDetectionEvidence(env);
+		if (detection) return `${env.mode.toUpperCase()} (${detection.key})`;
+		return env.mode.toUpperCase();
 	}
 	if (hint) {
 		// The stored mode and the evidence can disagree (a stale cache row):
@@ -470,6 +666,13 @@ export function describeWorkspaceMode(env: WorkspaceEnvResult): string {
 		}
 		return `UNKNOWN (${hint.key}=${hint.value} is not a known mode${where})`;
 	}
+	// A stale cache row can carry a detection next to an unknown mode: the
+	// detection names a mode, so the mode is shown.
+	const detection = findDetectionEvidence(env);
+	if (detection) {
+		const named = modeFromValue(detection.value);
+		if (named) return `${named.toUpperCase()} (${detection.key})`;
+	}
 	return "UNKNOWN (no NODE_ENV or environment variable found)";
 }
 
@@ -590,7 +793,7 @@ export function formatEnvForAgentResult(env: WorkspaceEnvResult): string {
 	}
 
 	message += `\n`;
-	message += `Build allowed: ${env.buildAllowed ? "yes" : "no - requires explicit request"}\n`;
+	message += `Build allowed: ${buildAllowanceReason(env)}\n`;
 
 	if (env.mode === "unknown") {
 		message += `\nNOTE: Environment unknown - a dev/build script only means a server CAN be started, it does not establish the workspace mode. Explicitly ask the user before build.\n`;

package/packages/contracts/src/workspace-env.ts

@@ -14,7 +14,7 @@
 
 import { DatabaseSync } from "node:sqlite";
 import { execSync } from "child_process";
-import { existsSync, readFileSync, mkdirSync, readlinkSync, realpathSync } from "fs";
+import { existsSync, readFileSync, readdirSync, mkdirSync, readlinkSync, realpathSync } from "fs";
 import { join } from "path";
 import { platform, totalmem, freemem } from "os";
 import {
@@ -26,12 +26,16 @@ import {
 	describeServerState,
 	describeWorkspaceMode,
 	detectModeHint,
+	DEPLOYMENT_MARKER_FILES,
 	filterOwnPids,
 	formatEnvForAgentResult,
 	formatEnvStatusLine as formatStatusLine,
 	formatWorkspacePath,
 	isLauncherCommand,
+	isLowRamWarning,
 	MASKED_MODE_VALUE,
+	MIN_BUILD_HEADROOM_GB,
+	modeFromRepositoryFacts,
 	modeFromValue,
 	orderDotenvFileNames,
 	parseDotenvVars,
@@ -41,6 +45,7 @@ import { readDotenvFiles } from "./workspace-dotenv.js";
 import type {
 	DotenvVar,
 	EnvEvidence,
+	RepositoryFacts,
 	ServerState,
 	WorkspaceEnvResult,
 	WorkspaceMode,
@@ -145,12 +150,11 @@ function detectRamInfo(): {
 		const freeBytes = freemem();
 		const totalGb = Math.round((totalBytes / (1024 ** 3)) * 10) / 10;
 		const availableGb = Math.round((freeBytes / (1024 ** 3)) * 10) / 10;
-		const LOW_RAM_GB = 16;
 
 		return {
 			total: totalGb,
 			available: availableGb,
-			lowWarning: totalGb < LOW_RAM_GB || availableGb < 4,
+			lowWarning: isLowRamWarning(totalGb, availableGb),
 		};
 	} catch {
 		return { total: null, available: null, lowWarning: false };
@@ -565,6 +569,99 @@ function detectPackageManager(workspacePath: string): string | null {
 	return null;
 }
 
+/**
+ * The git repository of a workspace.
+ *
+ * The root of the repository is the unit of the detection: a package
+ * published from a monorepo is described by the root, not by the folder
+ * the harness happens to run in.
+ */
+function detectGitFacts(workspacePath: string): { root: string; branch: string } {
+	try {
+		const out = execSync(
+			"git rev-parse --show-toplevel 2>/dev/null; git rev-parse --abbrev-ref HEAD 2>/dev/null",
+			{ cwd: workspacePath, encoding: "utf8", timeout: 1500 },
+		);
+		const lines = out.split("\n").map((line) => line.trim());
+		const root = lines[0] ?? "";
+		const branch = lines[1] ?? "";
+		// A detached HEAD reports "HEAD" - that is not a branch name.
+		return { root, branch: branch === "HEAD" ? "" : branch };
+	} catch {
+		// No git, no repository, or a timeout: nothing is known.
+		return { root: "", branch: "" };
+	}
+}
+
+/**
+ * True when the package is published to a registry.
+ *
+ * A package that is published names a version and declares what it ships
+ * ("files", "bin" or a "publishConfig"). A repository that only holds an
+ * application usually declares none of them - so this stays a careful
+ * signal instead of "every package.json is published".
+ */
+function isPublishedPackage(packageDir: string): boolean {
+	const pkgJsonPath = join(packageDir, "package.json");
+	if (!existsSync(pkgJsonPath)) return false;
+	try {
+		const pkg = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
+		if (!pkg || typeof pkg !== "object") return false;
+		if (pkg.private === true) return false;
+		if (typeof pkg.name !== "string" || !pkg.name) return false;
+		if (typeof pkg.version !== "string" || !pkg.version) return false;
+		return (
+			Array.isArray(pkg.files) ||
+			(typeof pkg.bin === "object" && pkg.bin !== null) ||
+			(typeof pkg.publishConfig === "object" && pkg.publishConfig !== null)
+		);
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * True when the repository carries a deployment configuration.
+ *
+ * A deployment file or a deploy workflow means the repository has a
+ * runtime environment of its own - the shape of the repository can then no
+ * longer say that the workspace is a development checkout.
+ */
+function hasDeploymentConfiguration(repoRoot: string): boolean {
+	for (const marker of DEPLOYMENT_MARKER_FILES) {
+		if (existsSync(join(repoRoot, marker))) return true;
+	}
+	const workflowDir = join(repoRoot, ".github", "workflows");
+	if (existsSync(workflowDir)) {
+		try {
+			for (const name of readdirSync(workflowDir)) {
+				if (/deploy/i.test(name)) return true;
+			}
+		} catch {
+			// An unreadable directory proves nothing.
+		}
+	}
+	return false;
+}
+
+/**
+ * Read the facts about the repository the workspace belongs to.
+ */
+function detectRepositoryFacts(
+	workspacePath: string,
+	hasRunningServer: boolean,
+): RepositoryFacts {
+	const { root, branch } = detectGitFacts(workspacePath);
+	const repoRoot = root || workspacePath;
+	return {
+		isGitRepository: root !== "",
+		branch,
+		isPublishedPackage: isPublishedPackage(repoRoot),
+		hasDeploymentMarker: hasDeploymentConfiguration(repoRoot),
+		hasRunningServer,
+	};
+}
+
 /**
  * Determine workspace mode with proper precedence
  * Never assume production - unknown requires investigation
@@ -576,11 +673,15 @@ function detectPackageManager(workspacePath: string): string | null {
  *    key whose value names a known mode, then any other environment shaped
  *    key
  * 3. an environment shaped key of the process env (the files are silent)
+ * 4. the facts about the repository (only when NO variable names the
+ *    environment at all) - a published source repository without a runtime
+ *    of its own is a development checkout
  */
 function determineMode(
 	processVars: DotenvVar[],
 	dotenvVars: DotenvVar[],
-	evidence: EnvEvidence[]
+	evidence: EnvEvidence[],
+	repositoryFacts: RepositoryFacts,
 ): WorkspaceMode {
 	const resolved = resolveWorkspaceMode(processVars, dotenvVars);
 	if (resolved.hint && resolved.source) {
@@ -599,8 +700,20 @@ function determineMode(
 			timestamp: Date.now(),
 			file: resolved.hint.file,
 		});
+		// An explicit variable decides - even when it names no known mode
+		// ("staging"). The mode stays unknown and the label names the value.
+		return resolved.mode;
 	}
-	return resolved.mode;
+	// No variable names the environment: the repository may still name it.
+	const detection = modeFromRepositoryFacts(repositoryFacts);
+	if (!detection) return resolved.mode;
+	evidence.push({
+		source: "detection",
+		key: detection.key,
+		value: detection.mode,
+		timestamp: Date.now(),
+	});
+	return detection.mode;
 }
 
 /**
@@ -655,14 +768,22 @@ export function detectWorkspaceEnv(workspacePath: string): WorkspaceEnvResult {
 		detectServerStates(workspacePath);
 
 	// Determine mode - NEVER assume production
-	const mode = determineMode(processVars, dotenvVars, evidence);
+	const repositoryFacts = detectRepositoryFacts(
+		workspacePath,
+		devServerState === "running" || buildServerState === "running",
+	);
+	const mode = determineMode(processVars, dotenvVars, evidence, repositoryFacts);
 
 	// Determine build permission
 	let buildAllowed = false;
 	if (mode === "production") {
 		buildAllowed = true; // Production build is allowed
 	} else if (mode === "development") {
-		buildAllowed = !ramInfo.lowWarning; // Allow if not low RAM
+		// A build needs headroom, not a big machine. The low-memory warning is
+		// about running a build AND a dev server in parallel; a build on its
+		// own only needs enough free memory to finish.
+		buildAllowed =
+			ramInfo.available === null ? false : ramInfo.available >= MIN_BUILD_HEADROOM_GB;
 	} else {
 		buildAllowed = false; // Unknown requires investigation
 	}

package/packages/contracts/test/workspace-env.test.ts

@@ -3,6 +3,7 @@ import { mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "n
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
+	buildAllowanceReason,
 	canShowModeValue,
 	collectDotenvVars,
 	collectProcessEnvVars,
@@ -16,7 +17,10 @@ import {
 	formatEnvStatusLine,
 	formatWorkspacePath,
 	isLauncherCommand,
+	isLowRamWarning,
+	isSessionVariableKey,
 	MASKED_MODE_VALUE,
+	modeFromRepositoryFacts,
 	modeFromValue,
 	orderDotenvFileNames,
 	parseDotenvVars,
@@ -623,3 +627,176 @@ describe("the template files of a workspace", () => {
 		expect(isTemplateDotenvName(".env.production")).toBe(false);
 	});
 });
+
+describe("the session variables of a desktop", () => {
+	test("a session variable is not an environment selector", () => {
+		expect(isSessionVariableKey("GNOME_SHELL_SESSION_MODE")).toBe(true);
+		expect(isSessionVariableKey("XDG_SESSION_TYPE")).toBe(true);
+		expect(isSessionVariableKey("DESKTOP_SESSION")).toBe(true);
+		expect(isSessionVariableKey("DBUS_SESSION_BUS_ADDRESS")).toBe(true);
+	});
+
+	test("a real environment selector is not a session variable", () => {
+		expect(isSessionVariableKey("NODE_ENV")).toBe(false);
+		expect(isSessionVariableKey("AMOS_ENV")).toBe(false);
+		expect(isSessionVariableKey("APP_MODE")).toBe(false);
+		expect(isSessionVariableKey("RAILS_ENV")).toBe(false);
+	});
+
+	test("a session variable never decides the mode of a workspace", () => {
+		// The scenario of the user: GNOME_SHELL_SESSION_MODE=ubuntu is set in
+		// every GNOME shell and must not make a source repository unknown.
+		const processVars = collectProcessEnvVars({
+			GNOME_SHELL_SESSION_MODE: "ubuntu",
+		});
+
+		expect(processVars).toEqual([]);
+		expect(resolveWorkspaceMode(processVars, []).mode).toBe("unknown");
+		expect(resolveWorkspaceMode(processVars, []).hint).toBeNull();
+	});
+
+	test("a session variable in a dotenv file does not decide the mode either", () => {
+		const vars = collectDotenvVars([
+			{ name: ".env", content: "XDG_SESSION_TYPE=x11\n" },
+		]);
+
+		expect(resolveWorkspaceMode([], vars).hint).toBeNull();
+	});
+
+	test("a session variable does not shadow a real environment selector", () => {
+		const vars = collectDotenvVars([
+			{ name: ".env", content: "GNOME_SHELL_SESSION_MODE=ubuntu\nAMOS_ENV=production\n" },
+		]);
+		const resolved = resolveWorkspaceMode([], vars);
+
+		expect(resolved.mode).toBe("production");
+		expect(resolved.hint?.key).toBe("AMOS_ENV");
+	});
+});
+
+describe("the mode detection of a source repository", () => {
+	const published = {
+		isGitRepository: true,
+		branch: "main",
+		isPublishedPackage: true,
+		hasDeploymentMarker: false,
+		hasRunningServer: false,
+	};
+
+	test("a published package without a runtime is a development checkout", () => {
+		expect(modeFromRepositoryFacts(published)).toEqual({
+			mode: "development",
+			key: "source-only repository",
+		});
+	});
+
+	test("a deployment configuration keeps the mode unknown", () => {
+		const detection = modeFromRepositoryFacts({
+			...published,
+			hasDeploymentMarker: true,
+		});
+
+		expect(detection).toBeNull();
+	});
+
+	test("a development branch is the fallback", () => {
+		expect(
+			modeFromRepositoryFacts({
+				...published,
+				branch: "develop",
+				isPublishedPackage: false,
+			}),
+		).toEqual({ mode: "development", key: "git branch develop" });
+		expect(
+			modeFromRepositoryFacts({
+				...published,
+				branch: "development",
+				isPublishedPackage: false,
+			}),
+		).toEqual({ mode: "development", key: "git branch development" });
+	});
+
+	test("a production branch is never a development checkout", () => {
+		expect(
+			modeFromRepositoryFacts({
+				...published,
+				branch: "main",
+				isPublishedPackage: false,
+			}),
+		).toBeNull();
+		expect(
+			modeFromRepositoryFacts({
+				...published,
+				branch: "production",
+				isPublishedPackage: false,
+			}),
+		).toBeNull();
+	});
+
+	test("a directory that is not a repository names no mode", () => {
+		expect(
+			modeFromRepositoryFacts({
+				...published,
+				isGitRepository: false,
+			}),
+		).toBeNull();
+	});
+
+	test("the label names the reason of the detection", () => {
+		const env = makeEnv({
+			mode: "development",
+			buildAllowed: true,
+			evidence: [
+				{ source: "detection", key: "source-only repository", value: "development", timestamp: 0 },
+			],
+		});
+
+		expect(describeWorkspaceMode(env)).toBe("DEVELOPMENT (source-only repository)");
+	});
+});
+
+describe("the low memory rule", () => {
+	test("flags a machine with almost no free memory", () => {
+		expect(isLowRamWarning(64, 2)).toBe(true);
+		expect(isLowRamWarning(16, 3.9)).toBe(true);
+	});
+
+	test("does not flag a small machine with real headroom", () => {
+		expect(isLowRamWarning(15, 6.6)).toBe(false);
+		expect(isLowRamWarning(8, 8)).toBe(false);
+	});
+
+	test("flags a big machine that ran out of memory", () => {
+		expect(isLowRamWarning(64, 3)).toBe(true);
+	});
+
+	test("does not flag an unknown memory state", () => {
+		expect(isLowRamWarning(null, null)).toBe(false);
+		expect(isLowRamWarning(null, 12)).toBe(false);
+	});
+});
+
+describe("the build permission", () => {
+	test("allows a build when the environment allows it", () => {
+		expect(buildAllowanceReason(makeEnv({ mode: "development", buildAllowed: true }))).toBe("yes");
+	});
+
+	test("asks for an explicit request when the mode is unknown", () => {
+		expect(
+			buildAllowanceReason(makeEnv({ mode: "unknown", buildAllowed: false, lowRamWarning: false })),
+		).toBe("no - requires explicit request");
+	});
+
+	test("names the memory shortage when the memory is the reason", () => {
+		expect(
+			buildAllowanceReason(makeEnv({ mode: "development", buildAllowed: false, lowRamWarning: true })),
+		).toBe("no - low memory");
+	});
+
+	test("appears in the agent context", () => {
+		const message = formatEnvForAgentResult(
+			makeEnv({ mode: "development", buildAllowed: false, lowRamWarning: true }),
+		);
+		expect(message).toContain("Build allowed: no - low memory");
+	});
+});

package/packages/cookie-sanitizer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/cookie-sanitizer",
-  "version": "1.1.394",
+  "version": "1.1.396",
   "description": "pi-harness-runtime — cookie sanitizer (provider-quota cookie file normaliser)",
   "type": "module",
   "main": "./dist/index.js",