pi-harness-runtime 1.1.394 → 1.1.396

package/packages/context-manager/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/context-manager",
-  "version": "1.1.394",
+  "version": "1.1.396",
   "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.
@@ -135,6 +159,14 @@ export declare const MASKED_MODE_VALUE = "<set>";
  * the name of an environment before its value may decide the mode.
  */
 export declare function isEnvShapedKey(key: string): boolean;
+/**
+ * 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 declare function isSessionVariableKey(key: string): boolean;
 /**
  * True for a key that may hold a secret.
  */
@@ -202,6 +234,61 @@ export interface ModeResolution {
     hint: DotenvVar | null;
     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 declare const DEPLOYMENT_MARKER_FILES: readonly ["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"];
+/**
+ * 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;
+}
+/**
+ * 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 declare function modeFromRepositoryFacts(facts: RepositoryFacts): RepositoryModeDetection | null;
 /**
  * Resolve the workspace mode from the variables that were found.
  *

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.
  *
@@ -167,6 +207,49 @@ export const MASKED_MODE_VALUE = "<set>";
 export function isEnvShapedKey(key) {
     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) {
+    const upper = key.toUpperCase();
+    return SESSION_VARIABLE_PREFIXES.some((prefix) => upper.startsWith(prefix));
+}
 /**
  * True for a key that may hold a secret.
  */
@@ -212,6 +295,9 @@ export function detectModeHint(vars, options = {}) {
     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.
@@ -219,7 +305,7 @@ export function detectModeHint(vars, options = {}) {
         // 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((v) => v.key !== "NODE_ENV" &&
+        const usable = usableVars.find((v) => v.key !== "NODE_ENV" &&
             isEnvShapedKey(v.key) &&
             modeFromValue(v.value) !== null);
         if (usable)
@@ -227,7 +313,7 @@ export function detectModeHint(vars, options = {}) {
     }
     // 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);
 }
 /**
  * The dotenv files of a workspace, in the order they are read.
@@ -289,12 +375,71 @@ export function collectProcessEnvVars(env = process.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 });
         }
     }
     return vars;
 }
+/**
+ * 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",
+];
+/**
+ * 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) {
+    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.
  *
@@ -346,6 +491,16 @@ function findModeEvidence(env) {
     // A value that names a known mode wins over a value that cannot be read.
     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) {
+    return env.evidence.find((e) => e.source === "detection");
+}
 /**
  * Human readable mode label.
  *
@@ -361,9 +516,14 @@ export function describeWorkspaceMode(env) {
     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):
@@ -382,6 +542,14 @@ export function describeWorkspaceMode(env) {
         }
         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)";
 }
 export function describeServerState(stateOrRunning, hasScript) {
@@ -481,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

@@ -13,10 +13,10 @@
  */
 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 { canShowModeValue, collectDotenvVars, collectProcessEnvVars, describeCwdCommand, describeOs, describeServerState, describeWorkspaceMode, detectModeHint, filterOwnPids, formatEnvForAgentResult, formatEnvStatusLine as formatStatusLine, formatWorkspacePath, isLauncherCommand, MASKED_MODE_VALUE, 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 {
@@ -520,6 +519,97 @@ function detectPackageManager(workspacePath) {
         return "npm";
     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) {
+    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) {
+    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) {
+    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, hasRunningServer) {
+    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
@@ -531,8 +621,11 @@ function detectPackageManager(workspacePath) {
  *    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, dotenvVars, evidence) {
+function determineMode(processVars, dotenvVars, evidence, repositoryFacts) {
     const resolved = resolveWorkspaceMode(processVars, dotenvVars);
     if (resolved.hint && resolved.source) {
         // The value is only kept when it is provably not a secret: the
@@ -546,8 +639,21 @@ function determineMode(processVars, dotenvVars, evidence) {
             timestamp: Date.now(),
             file: resolved.hint.file,
         });
-    }
-    return resolved.mode;
+        // 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;
+    }
+    // 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;
 }
 /**
  * Detect and store workspace environment
@@ -594,14 +700,19 @@ export function detectWorkspaceEnv(workspacePath) {
     // workspace (see detectServerStates).
     const { dev: devServerState, build: buildServerState } = 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/package.json

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