pi-harness-runtime 1.1.394 → 1.1.395

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

@@ -135,6 +135,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 +210,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

@@ -167,6 +167,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 +255,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 +265,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 +273,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 +335,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 +451,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 +476,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 +502,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) {

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, MASKED_MODE_VALUE, 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");
 /**
@@ -520,6 +520,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 +622,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 +640,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,7 +701,8 @@ 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") {

package/packages/contracts/package.json

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

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

@@ -231,6 +231,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 +327,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 +337,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 +347,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 +413,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 +432,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 +581,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 +607,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 +629,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)";
 }