pi-mega-compact 0.20.63 → 0.20.65

package/extensions/dashboard-client/src/tabs/SetupTab/CortexRuntimeInstallCard.tsx

@@ -0,0 +1,103 @@
+/**
+ * SetupTab/CortexRuntimeInstallCard.tsx — operator-run install guide card
+ * (ENC-2a).
+ *
+ * Pure render. When `SetupStatusResponse.nativeOrtInstallGuide` is non-null
+ * (opt-in on, effective runtime still wasm, platform installable), this card
+ * surfaces the three copy-paste steps the operator runs OUTSIDE the dashboard:
+ * install onnxruntime-node, restart via pi, and the expected next status. When
+ * the guide is null the card hides entirely (the modifiers card already
+ * surfaces the honest ENC-0g state).
+ *
+ * NO client-side execution — the install script is never spawned from here.
+ * Data comes exclusively from the existing /api/setup-status poll.
+ */
+import type React from "react";
+import { useState, useCallback, useEffect } from "react";
+import type { SetupStatusResponse } from "@contracts";
+import { fetchSetupStatus } from "../../api/client";
+import { styles } from "./CortexSetupStyles";
+
+function useCopyState(): [boolean, (text: string) => Promise<void>] {
+	const [copied, setCopied] = useState(false);
+	const copy = useCallback(async (text: string) => {
+		try {
+			await navigator.clipboard.writeText(text);
+			setCopied(true);
+			window.setTimeout(() => setCopied(false), 1500);
+		} catch {
+			setCopied(false);
+		}
+	}, []);
+	return [copied, copy];
+}
+
+export default function CortexRuntimeInstallCard(): React.ReactElement {
+	const [status, setStatus] = useState<SetupStatusResponse | null>(null);
+	const [copied, copy] = useCopyState();
+
+	const loadStatus = useCallback(() => {
+		fetchSetupStatus()
+			.then(setStatus)
+			.catch(() => {
+				/* best-effort poll; hide card when unavailable */
+			});
+	}, []);
+
+	useEffect(() => {
+		loadStatus();
+		const id = setInterval(loadStatus, 5000);
+		return () => clearInterval(id);
+	}, [loadStatus]);
+
+	const guide = status?.nativeOrtInstallGuide ?? null;
+	const installedVersion = status?.nativeOrtInstalledVersion ?? null;
+	if (!guide) return <></>;
+
+	return (
+		<div style={styles.section}>
+			<h3 style={styles.sectionTitle}>Encoder Runtime Install</h3>
+			<p style={{ ...styles.label, fontSize: "0.85rem", marginBottom: "0.75rem" }}>
+				Platform: {guide.platform}
+			</p>
+			{installedVersion !== null && (
+				<div style={styles.row}>
+					<span style={styles.label}>Detected:</span>
+					<span style={styles.value}>{installedVersion}</span>
+				</div>
+			)}
+			{guide.commands.map((command, i) => (
+				<div key={`${i}-${command}`} style={styles.row}>
+					<span style={styles.label}>Step {i + 1}:</span>
+					<code
+						style={{
+							...styles.mono,
+							display: "inline-block",
+							marginTop: "0.15rem",
+						}}
+					>
+						{command}
+					</code>
+					<button
+						type="button"
+						onClick={() => {
+							void copy(command);
+						}}
+						style={{ marginLeft: "0.5rem", fontSize: "0.8rem" }}
+					>
+						Copy
+					</button>
+				</div>
+			))}
+			<p style={{ ...styles.row, fontSize: "0.85rem" }}>
+				<span style={styles.label}>Script:</span>{" "}
+				<code style={styles.mono}>{guide.scriptPath}</code>
+			</p>
+			{copied && (
+				<p style={{ color: "#4caf50", fontSize: "0.8rem", margin: "0.25rem 0 0" }}>
+					Copied to clipboard
+				</p>
+			)}
+		</div>
+	);
+}

package/extensions/dashboard-client/src/tabs/SetupTab/CortexSetup.tsx

@@ -15,6 +15,8 @@ import { CortexEncoderCard } from "./CortexEncoderCard";
 import { CortexBlockersCard } from "./CortexBlockersCard";
 import { CortexActionsCard } from "./CortexActionsCard";
 import CortexRuntimeCard from "./CortexRuntimeCard";
+import CortexRuntimeInstallCard from "./CortexRuntimeInstallCard";
+import CortexRetestCard from "./CortexRetestCard";
 import { VectorCortexCosineFpCard } from "./VectorCortexCosineFpCard";
 import { VectorCortexRepoCorpusCard } from "./VectorCortexRepoCorpusCard";
 import { styles } from "./CortexSetupStyles";
@@ -43,6 +45,8 @@ export default function CortexSetup(): React.ReactElement {
 
 			<CortexEncoderCard data={state.data} error={state.error} />
 			<CortexRuntimeCard />
+			<CortexRuntimeInstallCard />
+			<CortexRetestCard />
 			<VectorCortexCosineFpCard />
 			<VectorCortexRepoCorpusCard />
 			<CortexBlockersCard

package/extensions/dashboard-server/api-contracts/setup.ts

@@ -64,6 +64,49 @@ export interface SetupStatusResponse {
    *  operand — persists even when `nativeOrtBudgetMib` is absent because the
    *  runtime applies the default when unset. Additive, flag-gated. */
   readonly nativeOrtBudgetEffectiveMib?: string;
+  /** ENC-2a: the native onnxruntime install-guide, present (as an object) when
+   *  the operator opted into the native backend AND the effective runtime is
+   *  still wasm (onnxruntime-node absent) AND the host platform is installable.
+   *  `null` when opt-in is off or the platform is unsupported/demoted (the guide
+   *  never renders). Built ONLY from the artifacts module constants — no inline
+   *  URLs or hashes in the route. Additive, flag-gated; absent = no guide. */
+  readonly nativeOrtInstallGuide?: {
+    /** The host's EncoderPlatform this guide is matched to. */
+    readonly platform: string;
+    /** The [install, restart, verify] copy-paste commands. */
+    readonly commands: readonly string[];
+    /** The committed operator script path (repo-rel). */
+    readonly scriptPath: string;
+  } | null;
+  /** ENC-2a: the installed native onnxruntime version read from
+   *  `~/.pi/mega-compact/native-ort/` when the probe marker/package is present
+   *  and platform-matched. Absent (NOT null) when not installed, so the client
+   *  hides the detected-version row. Additive, flag-gated, reader-only. */
+  readonly nativeOrtInstalledVersion?: string | null;
+  /** ENC-2b: the native onnxruntime qualification retest result, present (as an
+   *  object) when the flag is on AND a native binding is installed AND the
+   *  retest ran. `null` when the retest is flag-disabled; ABSENT when no binding
+   *  is installed (the client hides the retest card). Additive, flag-gated,
+   *  reader-only — computed per GET, never persisted. */
+  readonly nativeOrtRetestResult?: RetestResult | null;
+  /** ENC-2b: the effective backend AFTER the retest. `"native"` when the retest
+   *  verdict is `qualified`; `"wasm"` on a `degraded`/`failed` verdict or flag
+   *  off (the runtime never silently switches on a failed retest). Additive,
+   *  flag-gated, absent when no binding installed or flag off. */
+  readonly nativeOrtBackendEffective?: "native" | "wasm";
+}
+
+/** ENC-2b: the native onnxruntime qualification retest result, mirroring
+ *  `src/vector-cortex/encoder/native-qualify-retest.ts`. Surfaces only the
+ *  platform, version string, verdict, latency, and RSS — NEVER the binding
+ *  binary contents or model weights (SECURITY_PRIVACY). */
+export interface RetestResult {
+  readonly platform: string;
+  readonly version: string;
+  readonly verdict: "qualified" | "degraded" | "failed";
+  readonly p95Ms: number;
+  readonly rssMiB: number;
+  readonly testedAt: string;
 }
 
 /**
@@ -132,6 +175,17 @@ export interface SetupConfigureRequest {
    *  positive integer string within `ENC_2BUDGET_MAX_MIB` (validated; additive,
    *  flag-gated). */
   readonly nativeOrtBudgetMib?: string;
+  /** ENC-2a: an optional { boolean } guide-request key. `true` → 200 + the
+   *  guide echoed (this sprint conveys the GUIDE only — no server-side
+   *  execution); `false` → 400 `guide_rejected_false_nothing_to_do`.
+   *  Flag-gated, additive — ignored (no-op) when the flag is off. */
+  readonly nativeOrtInstallGuide?: boolean;
+  /** ENC-2b: an optional { boolean } retest-request key. `true` → runs the
+   *  native onnxruntime qualification retest synchronously (bounded, ~2s, the
+   *  binding is on disk from the ENC-2a install — never a fetch) and returns
+   *  the fresh result; `false` → 400 `retest_rejected_false_nothing_to_do`.
+   *  Flag-gated, additive — ignored (no-op) when the flag is off. */
+  readonly nativeOrtRetest?: boolean;
 }
 
 /** Response for POST /api/setup-configure. */

package/extensions/dashboard-server/routes-rag-settings-vector-cortex.ts

@@ -314,6 +314,18 @@ export const VECTOR_CORTEX_SETTINGS: SettingGroup = {
 			"ENC-2a exposes the runtime operator knob MEGACOMPACT_NATIVE_ORT_BUDGET_MIB (default 300 MiB, clamp 8192) as a dashboard Settings field. The knob gates budgetOk in the encoder runtime decision (decision.ts installBudgetMib + runtime-select.ts selectRuntimeBackend). Persisted to the per-repo .mega-compact.env via the setup-configure writer branch; the GET status route surfaces the persisted value AND the effective integer installBudgetMib() resolves to (so the dashboard shows the runtime's actual operand). OFF = no new GET fields, no writer branch, no new Settings rows (byte-identical ENC-1b predecessor).",
 			true,
 		),
+		boolDirect(
+			"MEGACOMPACT_ENC_2A",
+			"ENC-2a native onnxruntime install GUIDE (detect + copy-paste)",
+			"ENC-2a surfaces the platform-matched native onnxruntime install-guide (three copy-paste steps + script path) on the Setup Cortex sub-tab when the operator opted into the native backend but the effective runtime is still wasm (onnxruntime-node absent). Pure guidance — the extension NEVER executes or fetches (PREVENT-PI-004 unchanged); the committed operator script scripts/encoder/install-native-ort.mjs runs in the USER's shell. OFF = no guide GET fields, no guide-request POST branch, no install card (byte-identical ENC-1b predecessor).",
+			true,
+		),
+		boolDirect(
+			"MEGACOMPACT_ENC_2B",
+			"ENC-2b native ONNX runtime qualification retest (detect + re-qualify)",
+			"ENC-2b re-probes and re-qualifies the installed native onnxruntime binding (onnxruntime-node in ~/.pi/mega-compact/native-ort/, operator-installed via the ENC-2a guide): loads the LOCAL on-disk binding, runs a bounded warmup + p95 probe, measures RSS, and computes a fresh qualification verdict against the ENC-0f p95 budget + the operator install-budget. Never downloads or trains (PREVENT-PI-004 / HG-1 unchanged); surfaces nativeOrtRetestResult + nativeOrtBackendEffective on the GET /api/setup-status. OFF = no retest GET fields, no retest POST branch, no retest card (byte-identical ENC-2a predecessor).",
+			true,
+		),
 		boolDirect(
 			"MEGACOMPACT_COSINE_FP_BENCH",
 			"COS-FP-A Synthetic FP Bench",

package/extensions/dashboard-server/routes-setup-enc2a.ts

@@ -0,0 +1,140 @@
+/**
+ * dashboard-server/routes-setup-enc2a.ts — ENC-2a native onnxruntime install
+ * GUIDE (reader-only) + installed-version probe.
+ *
+ * Extracted out of routes-setup.ts (which hovers at the 300-line source soft
+ * cap, mirroring the ENC-1a/ENC-1b/ENC-2budget sibling extracts) so the
+ * ENC-2a additive GET fields — the platform-matched native install guide and
+ * the installed-version probe — live in a sibling impl file and routes-setup.ts
+ * stays a thin host.
+ *
+ * The guide's job is OPERATOR run-script assist: when the operator opted into
+ * the native backend (`MEGACOMPACT_ENCODER_NATIVE=1`) but the effective runtime
+ * is still `"wasm"` (onnxruntime-node not yet installed) AND the host platform
+ * is installable, the GET status response carries a `nativeOrtInstallGuide`
+ * object with the [install, restart, verify] copy-paste commands + the committed
+ * operator script path. The commands/URL/hash are built ONLY from the artifacts
+ * module constants (`src/vector-cortex/encoder/native-install-artifacts.ts`) —
+ * never an inline registry URL or literal hash (PREVENT-PI-004). The installed-
+ * version probe reads the local `~/.pi/mega-compact/native-ort/` package.json
+ * when present (reader-only filesystem read, zero network).
+ *
+ * The flag is off (or opt-in off / unsupported platform / non-wasm backend) ->
+ * guide `null` and installedVersion `null` -> the host omits both fields,
+ * byte-identical to the ENC-1b-era shape.
+ *
+ * Guardrails: PREVENT-PI-004 (local filesystem reads + in-memory backend
+ * selection only, zero network), PREVENT-001 (null-safe JSON), PREVENT-011
+ * (no `any`).
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { ENC_2A_ENABLED } from "../../src/config/vector-cortex.js";
+import { readEnc1bEnv } from "./routes-setup-enc1b.js";
+import { selectRuntimeBackend } from "../../src/vector-cortex/encoder/runtime-select.js";
+import { detectPlatform } from "../../src/vector-cortex/encoder/asset.js";
+import {
+  NATIVE_ORT_VERSION,
+  NATIVE_ORT_PACKAGE,
+  NATIVE_ORT_INSTALLABLE_PLATFORMS,
+} from "../../src/vector-cortex/encoder/native-install-artifacts.js";
+import type { SetupConfigureRequest } from "./api-contracts/setup.js";
+
+/** The committed operator script that performs the install (repo-relative). */
+const ENC_2A_SCRIPT_PATH = "scripts/encoder/install-native-ort.mjs";
+
+/** Where the operator script installs the native binding (absolute install
+ *  prefix used verbatim in the guide commands + the version probe). */
+function nativeOrtDir(): string {
+  return join(process.env.HOME ?? "", ".pi", "mega-compact", "native-ort");
+}
+
+/**
+ * True when the payload carries the ENC-2a guide-request key `false`/`true`
+ * (flag-gated, additive). `false` -> 400 (operator-driven no-op); `true` -> 200
+ * + the guide echoed (still no server execution — the execute path is ENC-2c).
+ * Flag-off -> null so the key falls through unrecognized (byte-identical
+ * ENC-1b-era predecessor).
+ */
+export function enc2aGuideRequest(
+  body: SetupConfigureRequest,
+): { status: 400 } | { status: 200 } | null {
+  if (!ENC_2A_ENABLED()) return null;
+  if (body.nativeOrtInstallGuide === true) return { status: 200 };
+  if (body.nativeOrtInstallGuide === false) return { status: 400 };
+  return null;
+}
+
+/**
+ * Read the ENC-2a native install GUIDE + installed-version, additive GET fields.
+ *
+ * The guide renders only when EVERY gate passes: flag on, operator opted into
+ * native, effective backend is still `"wasm"` (onnxruntime-node absent), and the
+ * host platform is installable (darwin-x64 is excluded — no native binding
+ * upstream, the ENC-0e demotion sentinel). The effective backend + demotion
+ * reason go through the EXISTING `selectRuntimeBackend` (reader-only — never a
+ * reimplemented literal). `installedVersion` probes
+ * `~/.pi/mega-compact/native-ort/node_modules/onnxruntime-node/package.json`
+ * when present; null otherwise. Returns `{ guide: null, installedVersion: null }`
+ * when the flag is off (byte-identical predecessor).
+ */
+export function readEnc2aGuide(stateDir: string): {
+  guide: { platform: string; commands: readonly string[]; scriptPath: string } | null;
+  installedVersion: string | null;
+} {
+  if (!ENC_2A_ENABLED()) return { guide: null, installedVersion: null };
+  const env = readEnc1bEnv(stateDir);
+  const platform = detectPlatform();
+  const chosen = selectRuntimeBackend({
+    platform: platform ?? "unsupported",
+    benchRecord: null,
+    nativeOptIn: env.nativeOptIn,
+  });
+  const backend = chosen.backend === "native" ? "native" : "wasm";
+
+  let guide: { platform: string; commands: readonly string[]; scriptPath: string } | null = null;
+  if (
+    env.nativeOptIn &&
+    backend === "wasm" &&
+    platform !== null &&
+    (NATIVE_ORT_INSTALLABLE_PLATFORMS as readonly string[]).includes(platform)
+  ) {
+    guide = {
+      platform,
+      commands: [
+        `npm install --prefix ${nativeOrtDir()} ${NATIVE_ORT_PACKAGE}@${NATIVE_ORT_VERSION}`,
+        "pi update --extensions && pi session-start",
+        "expect encoderBackend: native on next status poll",
+      ],
+      scriptPath: ENC_2A_SCRIPT_PATH,
+    };
+  }
+
+  return { guide, installedVersion: probeInstalledVersion() };
+}
+
+/** Probe the local native-ort package.json for the installed onnxruntime-node
+ *  version. Null when the package is absent/unreadable (reader-only, local). */
+function probeInstalledVersion(): string | null {
+  try {
+    const pkgPath = join(
+      nativeOrtDir(),
+      "node_modules",
+      NATIVE_ORT_PACKAGE,
+      "package.json",
+    );
+    if (!existsSync(pkgPath)) return null;
+    const raw = JSON.parse(readFileSync(pkgPath, "utf8")) as unknown;
+    if (
+      typeof raw === "object" &&
+      raw !== null &&
+      typeof (raw as { version?: unknown }).version === "string"
+    ) {
+      return (raw as { version: string }).version;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}

package/extensions/dashboard-server/routes-setup-enc2b.ts

@@ -0,0 +1,82 @@
+/**
+ * dashboard-server/routes-setup-enc2b.ts — ENC-2b native onnxruntime
+ * qualification retest (reader-only probe) + POST retest action.
+ *
+ * Extracted out of routes-setup.ts (which hovers at the 300-line source soft
+ * cap, mirroring the ENC-1b/ENC-2a sibling extracts) so the ENC-2b additive
+ * GET field — the native qualification retest result + effective backend —
+ * lives in a sibling impl file and routes-setup.ts stays a thin host.
+ *
+ * The retest's job is RE-QUALIFICATION: when the operator installed
+ * onnxruntime-node via the ENC-2a guide, the encoder read path does not
+ * automatically re-evaluate the qualification verdict. This sibling surface
+ * runs `runNativeRetest` (a bounded, reader-only, local probe) and:
+ *
+ *   - surfaces `nativeOrtRetestResult` + `nativeOrtBackendEffective` on the GET
+ *     when the flag is on AND a binding is installed — absent otherwise
+ *     (byte-identical to the ENC-2a-era shape on flag-off/none);
+ *   - handles the POST `nativeOrtRetest` key (`false` → 400
+ *     `retest_rejected_false_nothing_to_do`; `true` → run + echo the fresh
+ *     result; flag-off → the key is unrecognized, byte-identical predecessor).
+ *
+ * `nativeOrtBackendEffective` is `"native"` only when the retest verdict is
+ * `qualified`; any `degraded`/`failed` verdict keeps the backend `"wasm"` — the
+ * runtime never silently switches to a backend whose retest failed.
+ *
+ * Guardrails: PREVENT-PI-004 (local filesystem + in-process binding load only,
+ * zero network — the retest NEVER fetches), PREVENT-011 (no `any`).
+ */
+
+import { ENC_2B_ENABLED } from "../../src/config/vector-cortex.js";
+import {
+  runNativeRetest,
+  type RetestResult,
+} from "../../src/vector-cortex/encoder/native-qualify-retest.js";
+import type { SetupConfigureRequest } from "./api-contracts/setup.js";
+
+/**
+ * Resolve the ENC-2b additive GET fields. Returns BOTH fields when the flag is
+ * on AND a native binding is installed (the retest ran); returns `{}` on
+ * flag-off AND when no binding is installed — both fields are OMITTED (absent,
+ * not null), so the GET stays byte-identical to the ENC-2a-era shape and the
+ * client hides the retest card. Flag-off omits, never nulls: the ENC-2a-era
+ * host spreads `...{}` so no new key appears. Mirror of the ENC-2a/ENC-1b
+ * sibling idiom; async because the retest loads the binding in-process.
+ */
+export async function readEnc2bRetest(stateDir: string): Promise<{
+  nativeOrtRetestResult?: RetestResult;
+  nativeOrtBackendEffective?: "native" | "wasm";
+}> {
+  if (!ENC_2B_ENABLED()) return {};
+  const result = await runNativeRetest(stateDir);
+  if (result === null) return {};
+  return {
+    nativeOrtRetestResult: result,
+    nativeOrtBackendEffective: result.verdict === "qualified" ? "native" : "wasm",
+  };
+}
+
+/**
+ * ENC-2b POST retest-action key handling (flag-gated, additive).
+ *
+ * `true`  → { action: "run" } (the host runs the retest and returns the result)
+ * `false` → { action: "reject" } (400 `retest_rejected_false_nothing_to_do`)
+ * other   → null (key absent or flag off — falls through unrecognized,
+ *            byte-identical ENC-2a-era predecessor).
+ */
+export function enc2bRetestRequest(body: SetupConfigureRequest): "run" | "reject" | null {
+  if (!ENC_2B_ENABLED()) return null;
+  if (body.nativeOrtRetest === true) return "run";
+  if (body.nativeOrtRetest === false) return "reject";
+  return null;
+}
+
+/**
+ * Run the ENC-2b retest now (bounded, synchronous on the request) and return
+ * the fresh result. Flag-off or no binding → null. Used by the POST "run"
+ * branch; the result is returned on the response body, never persisted.
+ */
+export async function runEnc2bRetest(stateDir: string): Promise<RetestResult | null> {
+  if (!ENC_2B_ENABLED()) return null;
+  return runNativeRetest(stateDir);
+}

package/extensions/dashboard-server/routes-setup.ts

@@ -21,6 +21,8 @@ import {
 	tryEnc2BudgetInto,
 	enc2BudgetValidateCombined,
 } from "./routes-setup-enc2budget.js";
+import { readEnc2aGuide, enc2aGuideRequest } from "./routes-setup-enc2a.js";
+import { readEnc2bRetest, enc2bRetestRequest, runEnc2bRetest } from "./routes-setup-enc2b.js";
 import { writeEmbedderEnv } from "./routes-setup-env-upsert.js";
 import {
 	detectOllama,
@@ -85,10 +87,15 @@ export function handleSetupStatus(
 	}
 	const configured = detectConfiguredEmbedder(ctx.stateDir);
 	const active = detectCurrentEmbedder();
+	// ENC-2a (flag-gated, additive): the native install-guide + installed-version
+	// fields. Optional fields are added only when present/installable; when the
+	// flag is off readEnc2aGuide returns nulls so the body stays byte-identical
+	// to the ENC-1b-era shape.
+	const enc2a = readEnc2aGuide(ctx.stateDir);
 	// ENC-1a (flag-gated, additive): echo the persisted endpoint URL and an
 	// embeddingApiKeySet boolean ONLY — the raw API key is never returned. When
 	// the flag is off (or neither is set) both fields are simply omitted.
-	const body: SetupStatusResponse = {
+	const base: SetupStatusResponse = {
 		currentEmbedder: active,
 		configuredEmbedder: configured.embedder,
 		configuredUrl: configured.url,
@@ -100,10 +107,23 @@ export function handleSetupStatus(
 		),
 		...enc1aStatusFields(ctx.stateDir), ...enc1bStatusFields(ctx.stateDir),
 		...enc2BudgetStatusFields(ctx.stateDir),
+		...(enc2a.guide !== null ? { nativeOrtInstallGuide: enc2a.guide } : {}),
+		...(enc2a.installedVersion !== null ? { nativeOrtInstalledVersion: enc2a.installedVersion } : {}),
 	};
+	// ENC-2b (flag-gated, additive): the native qualification retest fields. The
+	// retest loads the on-disk binding in-process (bounded, never a fetch), so
+	// readEnc2bRetest is async; the handler returns true synchronously for the
+	// dispatch and writes the response after the await. Flag-off/none mutates
+	// the body additively and stays byte-identical to the ENC-2a-era shape.
 	// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
-	res.writeHead(200, { "Content-Type": "application/json" });
-	res.end(JSON.stringify(body));
+	readEnc2bRetest(ctx.stateDir).then((enc2b) => {
+		const body: SetupStatusResponse = { ...base, ...enc2b };
+		res.writeHead(200, { "Content-Type": "application/json" });
+		res.end(JSON.stringify(body));
+	}).catch(() => {
+		res.writeHead(200, { "Content-Type": "application/json" });
+		res.end(JSON.stringify(base));
+	});
 	return true;
 }
 
@@ -218,10 +238,52 @@ export function handleSetupConfigure(
 			return;
 		}
 		const body = parsed.value as unknown as SetupConfigureRequest;
+		// ENC-2a guide-request key (flag-gated, additive): `false` → 400 (an
+		// operator-driven no-op — this sprint conveys the GUIDE only, no server
+		// execution), `true` → 200 + the guide echoed (still no execution; the
+		// execute path is ENC-2c). Flag-off: enc2aGuideRequest returns null so the
+		// key falls through unrecognized (byte-identical ENC-1b-era predecessor).
+		const guideReq = enc2aGuideRequest(body);
+		// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+		if (guideReq !== null && guideReq.status === 400) {
+			res.writeHead(400, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({ error: "guide_rejected_false_nothing_to_do" }));
+			return;
+		}
 		// ENC-1a (flag-gated, additive): a pure external-embedder configure
 		// (new keys, no embedder selection) is handled by the sibling writer.
 		// Flag-off = the keys are simply not recognized, falling through to the
 		// pre-ENC-1a embedder path below (byte-identical predecessor).
+		if (guideReq !== null && guideReq.status === 200) {
+			// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+			res.writeHead(200, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({ nativeOrtInstallGuide: readEnc2aGuide(ctx.stateDir).guide }));
+			return;
+		}
+		// ENC-2b retest-action key (flag-gated, additive): `false` → 400 (an
+		// operator-driven no-op — nothing to retest), `true` → run the bounded
+		// retest synchronously and return the fresh result. Flag-off: the key
+		// falls through unrecognized (byte-identical ENC-2a-era predecessor).
+		// The retest never fetches — the binding is on disk from the ENC-2a
+		// install (PREVENT-PI-004 clean).
+		const retestReq = enc2bRetestRequest(body);
+		// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+		if (retestReq === "reject") {
+			res.writeHead(400, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({ error: "retest_rejected_false_nothing_to_do" }));
+			return;
+		}
+		if (retestReq === "run") {
+			// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+			runEnc2bRetest(ctx.stateDir).then((fresh) => {
+				res.writeHead(200, { "Content-Type": "application/json" });
+				res.end(JSON.stringify({ nativeOrtRetestResult: fresh }));
+			}).catch(() => {
+				res.writeHead(500, { "Content-Type": "application/json" });
+				res.end(JSON.stringify({ error: "retest_failed" }));
+			});
+			return;
+		}
 		if (tryEnc1aConfigure(body, res, ctx)) return;
 		if (tryEnc1bConfigure(body, res, ctx)) return; // pure ENC-1b configure (dim/headers/allow-remote/native)
 		// ENC-1b combined-payload validation: when a payload carries a valid

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.20.63",
+  "version": "0.20.65",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-3-Clause",

package/src/config/vector-cortex-enc2a.ts

@@ -0,0 +1,37 @@
+/**
+ * config/vector-cortex-enc2a.ts — ENC-2a native onnxruntime install-guide flag
+ * (operator run-script assist).
+ *
+ * Sibling of vector-cortex-enc1a.ts / vector-cortex-enc1b.ts /
+ * vector-cortex-enc2budget.ts so vector-cortex.ts stays under the 300-line soft
+ * limit (soft-as-hard gate). vector-cortex.ts re-exports the flag below and
+ * root src/config.ts re-exports it, so no consumer import path changes.
+ *
+ * ENC-2a, when the operator opted into the native backend
+ * (`MEGACOMPACT_ENCODER_NATIVE=1`) but `encoderBackend` is still `"wasm"`
+ * (onnxruntime-node absent / not yet installed), surfaces an "Encoder Runtime
+ * Install" card on the Cortex sub-tab with copy-paste operator commands: the
+ * install + restart + verify steps built ONLY from the artifacts-module
+ * constants (`src/vector-cortex/encoder/native-install-artifacts.ts`) — never
+ * an inline registry URL or hash in the route (PREVENT-PI-004). The guide
+ * renders only on an installable host platform; the ENC-0e darwin-x64 demotion
+ * sentinel keeps it absent on an Intel Mac (no native binding upstream).
+ *
+ * `MEGACOMPACT_ENC_2A=0` disables: no guide fields, no install card, no absent
+ * read — byte-identical to the ENC-1b predecessor. The flag MUST also be a
+ * dashboard SETTINGS toggle (visible in config UI, never in EXCLUDED_SETTINGS
+ * — see `feedback_dashboard-flags-toggleable` memory).
+ *
+ * Pi-agnostic, dependency-free (PREVENT-PI-004 / PREVENT-011).
+ */
+
+import { sprintFlag } from "./vector-cortex-flag.js";
+
+/**
+ * ENC-2a — operator run-script assist (dashboard install guide for the
+ * onnxruntime-node native binding). Default ON. `MEGACOMPACT_ENC_2A=0` disables
+ * and is byte-identical to the ENC-1b predecessor: no guide/absent fields, no
+ * install card. This flag MUST also be a dashboard SETTINGS toggle (visible in
+ * config UI, never in EXCLUDED_SETTINGS).
+ */
+export const ENC_2A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_ENC_2A");

package/src/config/vector-cortex-enc2b.ts

@@ -0,0 +1,38 @@
+/**
+ * config/vector-cortex-enc2b.ts — ENC-2b native onnxruntime qualification
+ * retest flag.
+ *
+ * Sibling of vector-cortex-enc2a.ts / vector-cortex-enc2budget.ts so
+ * vector-cortex.ts stays under the 300-line soft limit (soft-as-hard gate).
+ * vector-cortex.ts re-exports the flag below and root src/config.ts re-exports
+ * it, so no consumer import path changes.
+ *
+ * ENC-2b re-probes and re-qualifies the installed native onnxruntime binding
+ * (`onnxruntime-node` in `~/.pi/mega-compact/native-ort/`, operator-installed
+ * via the ENC-2a guide). When the operator installs the binding the read path
+ * does not automatically re-evaluate the qualification verdict; this sprint
+ * delivers a reader-only retest that loads the LOCAL on-disk binding, runs a
+ * bounded warmup + p95 probe against it, measures RSS, computes a fresh
+ * qualification verdict against the ENC-0f p95 budget + the operator
+ * install-budget, and surfaces it on the Setup Cortex sub-tab and the GET
+ * `/api/setup-status` response.
+ *
+ * `MEGACOMPACT_ENC_2B=0` disables: the GET omits both new retest fields, the
+ * POST ignores the retest-request key, the Cortex sub-tab renders no retest
+ * card — byte-identical to the ENC-2a predecessor. The flag MUST also be a
+ * dashboard SETTINGS toggle (visible in config UI, never in EXCLUDED_SETTINGS
+ * — see `feedback_dashboard-flags-toggleable` memory).
+ *
+ * Pi-agnostic, dependency-free (PREVENT-PI-004 / PREVENT-011).
+ */
+
+import { sprintFlag } from "./vector-cortex-flag.js";
+
+/**
+ * ENC-2b — native onnxruntime qualification retest (detect installed binding,
+ * re-probe p95/RSS, re-qualify). Default ON. `MEGACOMPACT_ENC_2B=0` disables and
+ * is byte-identical to the ENC-2a predecessor: no retest GET fields, no retest
+ * POST branch, no retest card. This flag MUST also be a dashboard SETTINGS
+ * toggle (visible in config UI, never in EXCLUDED_SETTINGS).
+ */
+export const ENC_2B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_ENC_2B");

package/src/config/vector-cortex.ts

@@ -92,6 +92,10 @@ export {
   ENC_2BUDGET_MAX_MIB,
   ENC_2BUDGET_DEFAULT_MIB,
 } from "./vector-cortex-enc2budget.js";
+// ENC-2a native onnxruntime install-guide flag extracted to vector-cortex-enc2a.ts.
+export { ENC_2A_ENABLED } from "./vector-cortex-enc2a.js";
+// ENC-2b native onnxruntime qualification-retest flag extracted to vector-cortex-enc2b.ts.
+export { ENC_2B_ENABLED } from "./vector-cortex-enc2b.js";
 // Breaker constants (TRIAD_RESILIENCE.md §breaker) extracted to vector-cortex-breakers.ts.
 export {
   BREAKER_WINDOW_MS,

package/src/config.ts

@@ -202,6 +202,8 @@ export {
   ENC_2BUDGET_NATIVE_ORT_BUDGET_ENV,
   ENC_2BUDGET_MAX_MIB,
   ENC_2BUDGET_DEFAULT_MIB,
+  ENC_2A_ENABLED,
+  ENC_2B_ENABLED,
   COSINE_FP_BENCH_ENABLED,
   COSINE_FP_REAL_ENABLED,
   REPO_CORPUS_ENABLED,