pi-harness-runtime 1.1.395 → 1.1.397

package/AGENTS.md

@@ -555,7 +555,10 @@ bun run build && bun run start   # Server deployment
 - 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; a `develop`/`development` branch is the fallback
-- System RAM → Low RAM warning (<16GB total or <4GB available)
+- System RAM → Low RAM warning (<4GB free, or a small machine (<16GB total)
+  with less than 6GB free). The warning is about the headroom that is
+  actually free, not about the size of the machine: a 15GB laptop with 6.5GB
+  free can build, a 32GB server with 3GB free cannot.
 - Running processes → dev/build server status
 
 The dotenv files are read from the WORKSPACE (not from the current working
@@ -616,6 +619,12 @@ command to use.
 | `Low RAM` | Never run parallel build + dev |
 | `Dev server running` | Reuse it, don't restart |
 
+The status line states the build permission with its reason: `Build allowed:
+yes`, `no - low memory` (not enough free memory) or `no - requires explicit
+request` (the mode is unknown, so the environment has to be investigated
+first). In development mode the permission follows the free memory (a build
+needs ~2GB), not the size of the machine.
+
 **Decision flow:**
 ```text
 Check process.env.NODE_ENV first (it decides, also when it names no known mode)
@@ -639,20 +648,41 @@ Production detection ≠ deployment authorization
 
 ## Centralized Application Logging
 
-All application logs can be shipped to **Cloudflare R2** (durable archive) and to the
-**unified webhook server** (live path). The pipeline lives in `packages/logging`
-(`@pi-harness/logging`); the harness uses the process-wide singleton from it.
+All application logs can be shipped to the **unified webhook server** (ingest path),
+which is the only component that writes to **Cloudflare R2** (durable archive). The
+pipeline lives in `packages/logging` (`@pi-harness/logging`); the harness uses the
+process-wide singleton from it.
+
+**Client side** (first success wins, the rest are skipped - a fallback chain, never
+a broadcast):
+
+```text
+producer -> classify -> redact -> sample -> buffer -> webhook -> local spool (~/.pi-harness-runtime/logs/spool)
+```
 
-**Delivery order** (first success wins, the rest are skipped):
+**Server side** (durable hand-off, then an independent upload):
 
 ```text
-producer -> redact -> sample -> buffer -> R2 -> webhook -> local spool (~/.pi-harness-runtime/logs/spool)
+POST /api/logs -> authenticate -> validate -> durable outbox -> 202
+                                              |
+                                              v
+                                    worker -> R2 -> done
 ```
 
 - The local spool is the fallback: if every transport fails the batch is written to
   disk as NDJSON and re-shipped on the next successful flush. Nothing is lost, only delayed.
 - The local log files (`~/.pi-harness-runtime/logs/*.jsonl`, `harness/*.log`) stay the
   source of truth. The centralized pipeline is a copy for the archive.
+- **Only the server writes to R2.** In `auto` mode the webhook is preferred when
+  `PI_LOG_WEBHOOK_URL` is set, so client machines need no R2 credentials.
+
+**What may leave the machine** (`classify`): an event allowlist decides, not a
+denylist. Structured service/session/validation events are remote; the catch-all
+`harness.log` mirror of a local log line, prompts, responses and command output stay
+local. A message only travels when it looks sanitized (one line, short, no path, no
+URL with a query string), and fields with a private key name (`prompt`, `output`,
+`path`, `url`, `user`, ...) are dropped. `PI_LOG_DIAGNOSTIC=1` relaxes the message rule
+for a user who explicitly asked for more - it never widens the event allowlist.
 
 **Configuration** (environment first, then `~/.pi-harness-runtime/keys/`):
 
@@ -667,6 +697,9 @@ producer -> redact -> sample -> buffer -> R2 -> webhook -> local spool (~/.pi-ha
 | `PI_LOG_FLUSH_INTERVAL_MS` | Automatic flush interval | `15000` |
 | `PI_LOG_WEBHOOK_URL` | Ingest URL of the webhook server | unset |
 | `PI_LOG_WEBHOOK_TOKEN` | Bearer token for the ingest endpoint | unset |
+| `PI_LOG_APP_VERSION` | Version reported with every batch | unset |
+| `PI_LOG_INSTALLATION_ID` | Stable id of this installation | generated once |
+| `PI_LOG_DIAGNOSTIC` | `1` allows raw messages (events stay allowlisted) | unset |
 | `PI_LOG_R2_BUCKET` / `PI_LOG_R2_ENDPOINT` / `PI_LOG_R2_ACCESS_KEY_ID` / `PI_LOG_R2_SECRET_ACCESS_KEY` | R2 credentials | key files |
 | `PI_LOG_SPOOL_DIR` | Local spool directory | `~/.pi-harness-runtime/logs/spool` |
 
@@ -677,9 +710,32 @@ R2 credentials are read from the key files `r2-bucket-name.txt`, `r2-endpoint.tx
 
 - Emit through the singleton: `centralInfo/centralWarn/centralError(source, event, message?, fields?)`.
   The `source` identifies the component, the `event` is a dotted name.
+- The event name decides whether a record may leave the machine. Use one of the
+  allowlisted shapes (`service.*`, `session.*`, `validation.*`, `harness.service-diagnostics.*`,
+  `harness.planner.decision`, `harness.glm-quota.quota`, ...) or a `warn`/`error` level.
+  An unknown event stays local.
 - Redaction is automatic (key names, credential patterns, truncation), but producers must
   not pass user content: prompts, raw model output and message bodies are dropped by the
   redactor, so shipping them is pointless.
 - Never put a credential in a log message. The redactor is a safety net, not a licence.
-- The webhook server exposes `POST /api/logs` for the ingest path. Set `LOG_INGEST_TOKEN`
-  to require a bearer token; the server re-redacts every batch and relays it to R2.
+- Prefer a structured event over mirroring a local log line. The `logToFile()` mirror
+  (`harness.log`) stays local on purpose - the local file is the source of truth.
+
+**Server endpoints** (all require an ingest credential):
+
+| Route | Method | Purpose |
+|-------|--------|---------|
+| `/api/logs` | POST | Accept a batch. `202` only after the durable write, `503` when the endpoint is not configured or the queue is unavailable (the client keeps its spool). |
+| `/api/logs/query` | POST | Read-only, tenant-scoped metadata query (installation, session, time range, level, source, event). Bounded and paginated; never returns message text. |
+| `/api/logs/health` | GET | Queue depth, oldest pending age, failure count, last error. |
+
+**Ingest credentials** (server side):
+
+- The endpoint **fails closed**: without a credential every write is refused with `503`.
+- `LOG_INGEST_TOKEN` (or `keys/log-ingest-token.txt`) is a shared token for a
+  single-tenant deployment; `LOG_INGEST_TENANT` names its tenant.
+- `keys/log-ingest-credentials.json` holds scoped credentials, one per installation:
+  `{ "id", "tenantId", "label", "scopes", "tokenHash", "createdAt", "revokedAt" }`.
+  Tokens are stored as SHA-256 hashes; the tenant is derived from the credential and
+  never from the request body.
+- Rotate by adding an entry and revoking the old one (`revokedAt`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-harness-runtime",
-  "version": "1.1.395",
+  "version": "1.1.397",
   "description": "[BETA] Codex-style /usage status + autonomous coding harness for pi. Not production ready — expect breaking changes.",
   "type": "module",
   "scripts": {

package/packages/a2a-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/a2a-adapter",
-  "version": "1.1.395",
+  "version": "1.1.397",
   "type": "module",
   "description": "Google Agent-to-Agent (A2A) protocol adapter for pi-harness",
   "main": "dist/index.js",

package/packages/agent-policy/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/agent-policy",
-  "version": "1.1.395",
+  "version": "1.1.397",
   "description": "Agent policy runtime for pi-harness - enforces mandatory rule delivery and mutation gating",
   "type": "module",
   "main": "./dist/index.js",

package/packages/architecture-generator/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/architecture-generator",
-  "version": "1.1.395",
+  "version": "1.1.397",
   "description": "Generate ADR and Mermaid diagrams from project analysis",
   "type": "module",
   "main": "./dist/index.js",

package/packages/auth/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/auth",
-  "version": "1.1.395",
+  "version": "1.1.397",
   "description": "pi-harness-runtime — auth",
   "type": "module",
   "main": "./dist/index.js",

package/packages/autonomous-refactor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/autonomous-refactor",
-  "version": "1.1.395",
+  "version": "1.1.397",
   "type": "module",
   "description": "Autonomous refactoring engine",
   "main": "dist/index.js",

package/packages/autonomous-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/autonomous-runtime",
-  "version": "1.1.395",
+  "version": "1.1.397",
   "description": "Autonomous Operations Runtime — task inbox, lease management, and worker lifecycle (RFC-0101)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/cache-strategy/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/cache-strategy",
-  "version": "1.1.395",
+  "version": "1.1.397",
   "type": "module",
   "description": "Smart caching with TTL and invalidation strategies (RFC-0022)",
   "main": "dist/index.js",

package/packages/capability-registry/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/capability-registry",
-  "version": "1.1.395",
+  "version": "1.1.397",
   "description": "Capability Registry for pi-harness-runtime — tracks model capabilities and enables capability-based routing",
   "type": "module",
   "main": "./dist/index.js",

package/packages/checkpoint/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/checkpoint",
-  "version": "1.1.395",
+  "version": "1.1.397",
   "description": "Enhanced checkpoint system with incremental snapshots, diff-based storage, and recovery strategies",
   "type": "module",
   "main": "./dist/index.js",

package/packages/cli-plugin-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/cli-plugin-sdk",
-  "version": "1.1.395",
+  "version": "1.1.397",
   "type": "module",
   "description": "CLI Plugin SDK for pi-harness — install, list, remove, update, invoke plugins",
   "main": "dist/index.js",

package/packages/clipboard/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/clipboard",
-  "version": "1.1.395",
+  "version": "1.1.397",
   "type": "module",
   "main": "src/index.ts",
   "exports": {

package/packages/clipboard-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/clipboard-plugin",
-  "version": "1.1.395",
+  "version": "1.1.397",
   "type": "module",
   "main": "src/index.ts",
   "exports": {

package/packages/code-generation/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/code-generation",
-  "version": "1.1.395",
+  "version": "1.1.397",
   "description": "Code generation pipeline for pi-harness-runtime",
   "type": "module",
   "main": "./dist/index.js",

package/packages/code-review/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/code-review",
-  "version": "1.1.395",
+  "version": "1.1.397",
   "description": "Automated code review engine for pi-harness-runtime",
   "type": "module",
   "main": "./dist/index.js",

package/packages/codex-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/codex-adapter",
-  "version": "1.1.395",
+  "version": "1.1.397",
   "type": "module",
   "description": "OpenAI Codex provider adapter for pi-harness",
   "main": "dist/index.js",

package/packages/codex-watcher/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/codex-watcher",
-  "version": "1.1.395",
+  "version": "1.1.397",
   "description": "Watches Codex CLI sessions and emits visible messages for PING-PONG monitoring",
   "type": "module",
   "main": "./dist/src/index.js",

package/packages/config-capture/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moocoding/config-capture",
-  "version": "1.1.395",
+  "version": "1.1.397",
   "description": "Auto-capture API-fetched configuration values to AGENTS.md",
   "type": "module",
   "main": "src/index.ts",

package/packages/connection-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/connection-runtime",
-  "version": "1.1.395",
+  "version": "1.1.397",
   "type": "module",
   "description": "Connection management with jittered exponential backoff for pi-harness",
   "main": "./dist/index.js",

package/packages/context-compiler/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/context-compiler",
-  "version": "1.1.395",
+  "version": "1.1.397",
   "description": "Bounded context selection engine for pi-harness-runtime",
   "type": "module",
   "main": "./dist/index.js",

package/packages/context-discovery/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/context-discovery",
-  "version": "1.1.395",
+  "version": "1.1.397",
   "type": "module",
   "main": "src/index.ts",
   "exports": {

package/packages/context-manager/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/context-manager",
-  "version": "1.1.395",
+  "version": "1.1.397",
   "description": "Context Window Manager — prevents model context overflow via compaction and resume prompts (RFC-0010)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/contracts/dist/workspace-env-format.d.ts

@@ -82,6 +82,30 @@ export interface WorkspaceEnvResult {
  * without the SQLite cache.
  */
 export declare function isLauncherCommand(cmdline: string): boolean;
+/**
+ * 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 declare function isLowRamWarning(totalGb: number | null, availableGb: number | null): boolean;
+/**
+ * The headroom a build needs before it is allowed in development mode.
+ */
+export declare 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 declare function buildAllowanceReason(env: WorkspaceEnvResult): string;
 export type ServerState = "running" | "not-detected" | "not-checked";
 /**
  * The name of the operating system the harness runs on.

package/packages/contracts/dist/workspace-env-format.js

@@ -31,6 +31,46 @@
 export function isLauncherCommand(cmdline) {
     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, availableGb) {
+    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) {
+    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";
+}
 /**
  * The name of the operating system the harness runs on.
  *
@@ -609,7 +649,7 @@ export function formatEnvForAgentResult(env) {
         }
     }
     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/dist/workspace-env.js

@@ -16,7 +16,7 @@ import { execSync } from "child_process";
 import { existsSync, readFileSync, readdirSync, mkdirSync, readlinkSync, realpathSync } from "fs";
 import { join } from "path";
 import { platform, totalmem, freemem } from "os";
-import { canShowModeValue, collectDotenvVars, collectProcessEnvVars, describeCwdCommand, describeOs, describeServerState, describeWorkspaceMode, detectModeHint, DEPLOYMENT_MARKER_FILES, filterOwnPids, formatEnvForAgentResult, formatEnvStatusLine as formatStatusLine, formatWorkspacePath, isLauncherCommand, MASKED_MODE_VALUE, modeFromRepositoryFacts, modeFromValue, orderDotenvFileNames, parseDotenvVars, resolveWorkspaceMode, } from "./workspace-env-format.js";
+import { canShowModeValue, collectDotenvVars, collectProcessEnvVars, describeCwdCommand, describeOs, 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, resolveWorkspaceMode, } from "./workspace-env-format.js";
 import { readDotenvFiles } from "./workspace-dotenv.js";
 const STORE_DIR = join(process.env.HOME || "/home/frappe", ".pi-harness-runtime");
 /**
@@ -95,11 +95,10 @@ 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 {
@@ -709,7 +708,11 @@ export function detectWorkspaceEnv(workspacePath) {
         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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/contracts",
-  "version": "1.1.395",
+  "version": "1.1.397",
   "type": "module",
   "description": "RPC schema definitions for pi-harness runtime",
   "main": "./dist/index.js",

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";
 
 /**
@@ -756,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

@@ -32,7 +32,9 @@ import {
 	formatEnvStatusLine as formatStatusLine,
 	formatWorkspacePath,
 	isLauncherCommand,
+	isLowRamWarning,
 	MASKED_MODE_VALUE,
+	MIN_BUILD_HEADROOM_GB,
 	modeFromRepositoryFacts,
 	modeFromValue,
 	orderDotenvFileNames,
@@ -148,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 };
@@ -778,7 +779,11 @@ export function detectWorkspaceEnv(workspacePath: string): WorkspaceEnvResult {
 	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,6 +17,7 @@ import {
 	formatEnvStatusLine,
 	formatWorkspacePath,
 	isLauncherCommand,
+	isLowRamWarning,
 	isSessionVariableKey,
 	MASKED_MODE_VALUE,
 	modeFromRepositoryFacts,
@@ -752,3 +754,49 @@ describe("the mode detection of a source repository", () => {
 		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.395",
+  "version": "1.1.397",
   "description": "pi-harness-runtime — cookie sanitizer (provider-quota cookie file normaliser)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/cost-optimizer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/cost-optimizer",
-  "version": "1.1.395",
+  "version": "1.1.397",
   "description": "Cost Optimizer for pi-harness-runtime — budget tracking, forecasting, and model selection optimization",
   "type": "module",
   "main": "./dist/index.js",

package/packages/dependency-analyzer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/dependency-analyzer",
-  "version": "1.1.395",
+  "version": "1.1.397",
   "type": "module",
   "main": "src/index.ts",
   "exports": {

package/packages/django-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/django-plugin",
-  "version": "1.1.395",
+  "version": "1.1.397",
   "description": "Django framework analysis — models, management commands, settings",
   "type": "module",
   "main": "./dist/index.js",