feat(runtime): explicit dev-binary override with forward decoder support

extensions/gentle-ai.ts

@@ -107,8 +107,16 @@ import {
 } from "../lib/review-snapshot.ts";
 import { sanitizeTerminalText, stripAnsi } from "../lib/terminal-theme.ts";
 import { CandidateViewError, CandidateViewRegistry, injectReviewCandidateView, readCandidateContextManifestPage, resolveCanonicalCandidateBase, type CandidateView } from "../lib/review-candidate-view.ts";
+import {
+	GentleAiDevBinaryOverrideError,
+	registerGentleAiDevBinary,
+	resolveGentleAiDevBinaryOverride,
+	unregisterGentleAiDevBinary,
+	type GentleAiDevBinaryOverride,
+} from "../lib/gentle-ai-binary.ts";
 import {
 	createNativeReviewCli,
+	createNodeExecFileAdapter,
 	isCanonicalProcessString,
 	nativeReviewAbandonAuthorization,
 	nativeReviewLegacyAliasRepairAuthorization,
@@ -6513,6 +6521,15 @@ function createGentleAiExtensionForTesting(
 	}
 
 	pi.on("session_start", async (_event, ctx) => {
+		// Loud, every session: an active dev-binary override means this session
+		// runs an unpinned gentle-ai. Announce which one before anything else.
+		try {
+			const devBinary = await describeDevBinaryOverride();
+			if (ctx.hasUI && devBinary.state === "active") ctx.ui.notify(devBinary.line, "warning");
+			if (ctx.hasUI && devBinary.state === "invalid") ctx.ui.notify(devBinary.line, "error");
+		} catch (error) {
+			if (ctx.hasUI) ctx.ui.notify(`Gentle AI dev binary override check failed: ${error instanceof Error ? error.message : String(error)}`, "warning");
+		}
 		try {
 			const transactionRecovery = reconcileCommitTransaction(ctx.cwd);
 			if (ctx.hasUI && transactionRecovery.status !== "clean") {
@@ -6825,6 +6842,66 @@ function createGentleAiExtensionForTesting(
 		},
 	});
 
+	// Dev-binary override surfacing (unpinned field-test mode). While the
+	// override is active every diagnostic surface names the exact binary, its
+	// live version, and its fresh content digest, so the maintainer always
+	// knows which gentle-ai actually answered. An invalid override surfaces as
+	// a failure — it is never silently ignored, because the native resolver
+	// refuses to fall back to the pin while an override is declared.
+	const describeDevBinaryOverride = async (): Promise<
+		| { state: "inactive" }
+		| { state: "active"; line: string; override: GentleAiDevBinaryOverride }
+		| { state: "invalid"; line: string }
+	> => {
+		let override: GentleAiDevBinaryOverride | undefined;
+		try {
+			override = resolveGentleAiDevBinaryOverride();
+		} catch (error) {
+			if (error instanceof GentleAiDevBinaryOverrideError) return { state: "invalid", line: `Gentle AI dev binary override invalid — ${error.message}` };
+			throw error;
+		}
+		if (override === undefined) return { state: "inactive" };
+		let version = "version unavailable";
+		try {
+			const adapter = createNodeExecFileAdapter();
+			const result = await adapter({ file: override.path, arguments: ["version"], cwd: dirname(override.path), timeoutMs: 10_000, maxBufferBytes: 1024 * 1024 });
+			const banner = result.stdout.trim();
+			if (result.exitCode === 0 && banner.startsWith("gentle-ai ")) version = banner.slice("gentle-ai ".length);
+		} catch {
+			// The doctor line still names the binary; the version stays unavailable.
+		}
+		return {
+			state: "active",
+			override,
+			line: `Gentle AI dev binary override active (unpinned, field-test only): ${override.path} ${version} sha256:${override.sha256.slice(0, 16)}`,
+		};
+	};
+
+	pi.registerCommand("gentle:dev-binary", {
+		description: "Register, inspect, or clear the persistent Gentle AI dev-binary override (status | <absolute path> | off). Unpinned, field-test only.",
+		handler: async (args, ctx) => {
+			const argument = args.trim();
+			try {
+				if (argument === "off") {
+					const removed = unregisterGentleAiDevBinary();
+					ctx.ui.notify(removed ? "Gentle AI dev binary registration removed; the pinned binary is active again." : "No dev binary registration to remove.", "info");
+					return;
+				}
+				if (argument === "" || argument === "status") {
+					const described = await describeDevBinaryOverride();
+					if (described.state === "inactive") ctx.ui.notify("No dev binary override; the pinned Gentle AI binary is active.", "info");
+					else ctx.ui.notify(described.line, described.state === "active" ? "warning" : "error");
+					return;
+				}
+				registerGentleAiDevBinary(argument);
+				const described = await describeDevBinaryOverride();
+				ctx.ui.notify(described.state === "inactive" ? "Dev binary registration written." : described.line, "warning");
+			} catch (error) {
+				ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+			}
+		},
+	});
+
 	pi.registerCommand("gentle:doctor", {
 		description: "Run read-only Gentle AI diagnostics for this Pi workspace.",
 		handler: async (_args, ctx) => {
@@ -6844,6 +6921,7 @@ function createGentleAiExtensionForTesting(
 			const localSddAgentOverrides = sddLocalAgentOverrideCount(ctx.cwd);
 			const modelConfig = await readSavedModelConfigAsync(ctx.cwd);
 			const engramActive = hasWritableEngramTool(pi);
+			const devBinary = await describeDevBinaryOverride();
 			const lines = [
 				"el Gentleman doctor",
 				`${agentsInstalled ? "pass" : "fail"}: Global SDD agents ${agentsInstalled ? "installed" : "missing"}`,
@@ -6855,6 +6933,8 @@ function createGentleAiExtensionForTesting(
 				`${modelConfig.status === "invalid" ? "fail" : "pass"}: Global model config ${modelConfig.status}`,
 				"pass: Sensitive-path guard active for read/write/edit tools",
 				`${engramActive ? "pass" : "warn"}: Engram memory tools ${engramActive ? "active" : "not active in this session"}`,
+				...(devBinary.state === "active" ? [`warn: ${devBinary.line}`] : []),
+				...(devBinary.state === "invalid" ? [`fail: ${devBinary.line}`, "remedy: fix the dev binary override or clear it with /gentle:dev-binary off (or unset GENTLE_PI_GENTLE_AI_DEV_BINARY)"] : []),
 			];
 			if (!agentsInstalled || !chainsInstalled) {
 				lines.push("remedy: run /gentle:install-sdd --force to refresh global SDD assets intentionally");
@@ -6931,9 +7011,11 @@ function createGentleAiExtensionForTesting(
 			const staleSddAssets = sddGlobalAssetDriftCount();
 			const localSddAgentOverrides = sddLocalAgentOverrideCount(ctx.cwd);
 			const modelConfig = await readModelConfigAsync(ctx.cwd);
+			const devBinary = await describeDevBinaryOverride();
 			ctx.ui.notify(
 				[
 					"el Gentleman package is active.",
+					...(devBinary.state === "inactive" ? [] : [devBinary.line]),
 					`Persona: ${readPersonaMode(ctx.cwd)}`,
 					`Global SDD agents: ${agentsInstalled ? "installed" : "not installed"}`,
 					`Global SDD chains: ${chainsInstalled ? "installed" : "not installed"}`,
@@ -6951,7 +7033,7 @@ function createGentleAiExtensionForTesting(
 					`Global model config: ${existsSync(modelConfigPath(ctx.cwd)) ? "present" : "missing"}`,
 					...describeModelConfig(ctx.cwd, modelConfig),
 				].join("\n"),
-				staleSddAssets > 0 || localSddAgentOverrides > 0 ? "warning" : "info",
+				staleSddAssets > 0 || localSddAgentOverrides > 0 || devBinary.state !== "inactive" ? "warning" : "info",
 			);
 		},
 	});

lib/gentle-ai-binary.ts

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
-import { existsSync, lstatSync, readFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import {
 	GENTLE_AI_INSTALL_METHOD,
@@ -46,6 +47,165 @@ function sha256(value: Buffer): string {
 	return createHash("sha256").update(value).digest("hex");
 }
 
+// ---------------------------------------------------------------------------
+// Dev-binary override — the maintainer field-test lane.
+//
+// Two explicit activation paths, in precedence order:
+//   1. GENTLE_PI_GENTLE_AI_DEV_BINARY (session override, absolute path), then
+//   2. the persistent registration file at
+//      <GENTLE_PI_CONFIG_HOME|~/.pi/gentle-ai>/dev-binary.json with the strict
+//      shape {"schema":"gentle-pi.dev-binary/v1","path":"<absolute path>"}.
+//
+// The registration deliberately pins no digest: it is the unpinned field-test
+// mode, and the binary at that path changes on every rebuild. Every resolution
+// re-validates the file and recomputes the sha256, so a rebuilt binary is
+// followed automatically with a fresh digest and no re-registration.
+//
+// Guardrails per resolution: absolute path, regular non-symlink file, POSIX
+// executable. Any failure — including a malformed registration document or a
+// registered-but-missing binary — is a typed error naming its origin, never a
+// silent fallback to the pinned binary: silently running the pin while the
+// maintainer believes he is field-testing main is the worst possible outcome.
+// With neither activation path present, the pinned supply-chain resolution
+// below stays byte-identical.
+// ---------------------------------------------------------------------------
+
+export const GENTLE_AI_DEV_BINARY_ENV = "GENTLE_PI_GENTLE_AI_DEV_BINARY";
+export const GENTLE_AI_DEV_BINARY_REGISTRATION_SCHEMA = "gentle-pi.dev-binary/v1";
+export const GENTLE_AI_DEV_BINARY_OVERRIDE_INVALID_CODE = "dev-binary-override-invalid";
+
+export interface GentleAiDevBinaryEnvironment {
+	env: Record<string, string | undefined>;
+	home: string;
+}
+
+export interface GentleAiDevBinaryOverride {
+	source: "env" | "registration";
+	/** The env var name or registration file path that selected this binary. */
+	origin: string;
+	path: string;
+	sha256: string;
+}
+
+export class GentleAiDevBinaryOverrideError extends Error {
+	readonly code = GENTLE_AI_DEV_BINARY_OVERRIDE_INVALID_CODE;
+	readonly source: "env" | "registration";
+	readonly origin: string;
+	constructor(source: "env" | "registration", origin: string, reason: string) {
+		super(`${GENTLE_AI_DEV_BINARY_OVERRIDE_INVALID_CODE}: ${origin} ${reason}. Fix or remove the override; the pinned binary is never used silently while an override is declared.`);
+		this.name = "GentleAiDevBinaryOverrideError";
+		this.source = source;
+		this.origin = origin;
+	}
+}
+
+let devBinaryEnvironmentTestingOverlay: GentleAiDevBinaryEnvironment | undefined;
+
+/** Testing-only environment overlay; production code never calls this. */
+export function setGentleAiDevBinaryEnvironmentForTesting(environment: GentleAiDevBinaryEnvironment | undefined): void {
+	devBinaryEnvironmentTestingOverlay = environment;
+}
+
+function ambientDevBinaryEnvironment(): GentleAiDevBinaryEnvironment {
+	return devBinaryEnvironmentTestingOverlay ?? { env: process.env, home: homedir() };
+}
+
+export function gentleAiDevBinaryRegistrationPath(environment: GentleAiDevBinaryEnvironment = ambientDevBinaryEnvironment()): string {
+	const configHome = environment.env.GENTLE_PI_CONFIG_HOME ?? join(environment.home, ".pi", "gentle-ai");
+	return join(configHome, "dev-binary.json");
+}
+
+function validateDevBinary(source: "env" | "registration", origin: string, path: string, platform: string): GentleAiDevBinaryOverride {
+	if (typeof path !== "string" || path.length === 0) throw new GentleAiDevBinaryOverrideError(source, origin, "declares an empty dev binary path");
+	if (!isAbsolute(path)) throw new GentleAiDevBinaryOverrideError(source, origin, `must name an absolute path, received "${path}"`);
+	let details: ReturnType<typeof lstatSync>;
+	try {
+		details = lstatSync(path);
+	} catch {
+		throw new GentleAiDevBinaryOverrideError(source, origin, `names "${path}", which does not exist`);
+	}
+	if (!details.isFile() || details.isSymbolicLink()) throw new GentleAiDevBinaryOverrideError(source, origin, `names "${path}", which is not a regular non-symlink file`);
+	if (platform !== "win32" && (details.mode & 0o111) === 0) throw new GentleAiDevBinaryOverrideError(source, origin, `names "${path}", which is not a POSIX executable`);
+	let digest: string;
+	try {
+		digest = sha256(readFileSync(path));
+	} catch {
+		throw new GentleAiDevBinaryOverrideError(source, origin, `names "${path}", which could not be read`);
+	}
+	return { source, origin, path, sha256: digest };
+}
+
+function readDevBinaryRegistration(registrationPath: string): string {
+	let contents: string;
+	try {
+		contents = readFileSync(registrationPath, "utf8");
+	} catch {
+		throw new GentleAiDevBinaryOverrideError("registration", registrationPath, "could not be read");
+	}
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(contents);
+	} catch {
+		throw new GentleAiDevBinaryOverrideError("registration", registrationPath, "is not valid JSON");
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new GentleAiDevBinaryOverrideError("registration", registrationPath, "must be a JSON object");
+	const record = parsed as Record<string, unknown>;
+	const keys = Object.keys(record).sort();
+	if (keys.length !== 2 || keys[0] !== "path" || keys[1] !== "schema") throw new GentleAiDevBinaryOverrideError("registration", registrationPath, `must carry exactly the keys "schema" and "path"`);
+	if (record.schema !== GENTLE_AI_DEV_BINARY_REGISTRATION_SCHEMA) throw new GentleAiDevBinaryOverrideError("registration", registrationPath, `must declare schema ${GENTLE_AI_DEV_BINARY_REGISTRATION_SCHEMA}`);
+	if (typeof record.path !== "string" || record.path.length === 0) throw new GentleAiDevBinaryOverrideError("registration", registrationPath, "must declare a non-empty string path");
+	return record.path;
+}
+
+/**
+ * Resolves the active dev-binary override, if any. Returns undefined only when
+ * neither activation path is present; a present-but-invalid override always
+ * throws a typed GentleAiDevBinaryOverrideError naming its origin.
+ */
+export function resolveGentleAiDevBinaryOverride(
+	environment: GentleAiDevBinaryEnvironment = ambientDevBinaryEnvironment(),
+	platform = process.platform,
+): GentleAiDevBinaryOverride | undefined {
+	const envValue = environment.env[GENTLE_AI_DEV_BINARY_ENV];
+	if (envValue !== undefined && envValue.length > 0) return validateDevBinary("env", GENTLE_AI_DEV_BINARY_ENV, envValue, platform);
+	const registrationPath = gentleAiDevBinaryRegistrationPath(environment);
+	if (!existsSync(registrationPath)) return undefined;
+	return validateDevBinary("registration", registrationPath, readDevBinaryRegistration(registrationPath), platform);
+}
+
+/**
+ * Cheap presence probe: is a dev-binary override declared at all? Used by the
+ * native CLI to select the unpinned version gate without hashing the binary.
+ * Declared-but-invalid still counts as configured — the resolution path will
+ * fail loudly with the typed error instead of quietly using the pin.
+ */
+export function gentleAiDevBinaryOverrideConfigured(environment: GentleAiDevBinaryEnvironment = ambientDevBinaryEnvironment()): boolean {
+	const envValue = environment.env[GENTLE_AI_DEV_BINARY_ENV];
+	if (envValue !== undefined && envValue.length > 0) return true;
+	return existsSync(gentleAiDevBinaryRegistrationPath(environment));
+}
+
+/** Validates and persistently registers a dev binary; returns the fresh override. */
+export function registerGentleAiDevBinary(
+	path: string,
+	environment: GentleAiDevBinaryEnvironment = ambientDevBinaryEnvironment(),
+	platform = process.platform,
+): { registrationPath: string; override: GentleAiDevBinaryOverride } {
+	const registrationPath = gentleAiDevBinaryRegistrationPath(environment);
+	const validated = validateDevBinary("registration", registrationPath, path, platform);
+	mkdirSync(dirname(registrationPath), { recursive: true });
+	writeFileSync(registrationPath, `${JSON.stringify({ schema: GENTLE_AI_DEV_BINARY_REGISTRATION_SCHEMA, path })}\n`);
+	return { registrationPath, override: validated };
+}
+
+/** Deletes the persistent registration; returns whether one existed. */
+export function unregisterGentleAiDevBinary(environment: GentleAiDevBinaryEnvironment = ambientDevBinaryEnvironment()): boolean {
+	const registrationPath = gentleAiDevBinaryRegistrationPath(environment);
+	if (!existsSync(registrationPath)) return false;
+	rmSync(registrationPath);
+	return true;
+}
+
 function isConfined(path: string, directory: string): boolean {
 	const relativePath = relative(directory, path);
 	return relativePath !== "" && !relativePath.startsWith("..") && !isAbsolute(relativePath);
@@ -110,7 +270,14 @@ export function resolveGentleAiBinary(
 	packageRoot = dirname(dirname(fileURLToPath(import.meta.url))),
 	platform = process.platform,
 	readBinary: (path: string) => Buffer = readFileSync,
+	environment: GentleAiDevBinaryEnvironment = ambientDevBinaryEnvironment(),
 ): string {
+	// The explicit dev-binary override wins over the pinned supply-chain path.
+	// Its typed errors propagate: a declared override never falls back to the
+	// pin. Without a declared override this call returns undefined and the
+	// pinned resolution below is byte-identical to the pre-override behavior.
+	const override = resolveGentleAiDevBinaryOverride(environment, platform);
+	if (override !== undefined) return override.path;
 	const binaryPath = gentleAiBinaryPath(packageRoot, platform);
 	const versionDirectory = dirname(binaryPath);
 	const manifestPath = join(versionDirectory, "integrity.json");