pi-mega-compact 0.20.48 → 0.20.50

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

@@ -0,0 +1,50 @@
+/**
+ * SetupTab/EmbedderSetupHelpers.tsx — extracted render helpers for EmbedderSetup.
+ *
+ * Split from EmbedderSetup.tsx to respect the extensions/ 400-line soft limit
+ * (ENC-1a pushed the embedder card over its cap, so the helpers were extracted).
+ */
+import type React from "react";
+import type { SetupStatusResponse } from "@contracts";
+import { styles } from "./EmbedderSetupStyles";
+
+/** Human label for an embedder identifier. */
+export function embedderLabel(e: string): string {
+	switch (e) {
+		case "trigram":
+			return "TrigramEmbedder (heuristic, default)";
+		case "http":
+			return "HTTP Embedder (BYO localhost)";
+		case "minilm":
+			return "MiniLM (experimental)";
+		default:
+			return "Unknown";
+	}
+}
+
+/** Warn when the active embedder is the heuristic trigram default. */
+export function trigramWarning(status: SetupStatusResponse | null): React.ReactElement | null {
+	if (status?.currentEmbedder !== "trigram") return null;
+	return (
+		<div style={styles.warning}>
+			<strong>Note:</strong> TrigramEmbedder is a heuristic-strength default
+			embedder. It works without any setup but recall quality may be lower
+			than a dedicated embedding backend. If you notice poor recall results,
+			consider installing Ollama and running the{" "}
+			<code>/megasetup</code> command, or set{" "}
+			<code>MEGACOMPACT_EMBEDDING_URL</code> to point at your own localhost
+			embedding server.
+		</div>
+	);
+}
+
+/** Installed / not-found badge dot for a detection row. */
+export function detectBadge(installed: boolean): React.ReactElement {
+	const bg = installed ? "#1a5a1a" : "#3a1a1a";
+	const color = installed ? "#4caf50" : "#f44336";
+	return (
+		<span style={{ ...styles.badge, background: bg, color }}>
+			{installed ? "Detected" : "Not found"}
+		</span>
+	);
+}

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

@@ -21,8 +21,12 @@ export interface BlockerV1 {
   readonly title: string;
   /** Severity: blocker | high | medium. */
   readonly severity: "blocker" | "high" | "medium";
-  /** Lifecycle state — always "open" (hard gates not closed in-workstream). */
-  readonly status: "open";
+  /**
+   * Lifecycle state. "open" (hard gate unresolved), "closed" (re-derived by
+   * the ENC-0g computed blocker list, e.g. HG-1 once five heads exist), or
+   * "superseded" (an open question with no live measurement on this device).
+   */
+  readonly status: "open" | "closed" | "superseded";
   /** Optional candidate resolution surfaced for the user / controller. */
   readonly resolution?: string;
 }

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

@@ -27,6 +27,12 @@ export interface SetupStatusResponse {
   readonly embedCache: string | null;
   /** Whether MEGACOMPACT_MINILM is set to a truthy value. */
   readonly minilm: boolean;
+  /** ENC-1a: the external embedder endpoint URL persisted in the per-repo
+   *  `.mega-compact.env`, when one is configured (additive, flag-gated). */
+  readonly embeddingEndpointUrl?: string;
+  /** ENC-1a: whether an external embedder API key is configured. The raw key is
+   *  NEVER returned — only this boolean presence marker (additive, flag-gated). */
+  readonly embeddingApiKeySet?: boolean;
 }
 
 /**
@@ -72,6 +78,12 @@ export interface SetupConfigureRequest {
   readonly embedder: "ollama" | "llama" | "trigram" | "custom" | "onnx";
   /** Override URL (required for "custom"; optional defaults for ollama/llama/onnx). */
   readonly url?: string;
+  /** ENC-1a: external embedder endpoint URL, persisted to the per-repo
+   *  `.mega-compact.env` (additive, flag-gated). */
+  readonly embeddingEndpointUrl?: string;
+  /** ENC-1a: external embedder API key, persisted to the per-repo
+   *  `.mega-compact.env` only — never returned by any GET (additive, flag-gated). */
+  readonly embeddingApiKey?: string;
 }
 
 /** Response for POST /api/setup-configure. */

package/extensions/dashboard-server/qualification-record.ts

@@ -0,0 +1,70 @@
+/**
+ * dashboard-server/qualification-record.ts — ENC-0g QualificationV1 reader.
+ *
+ * Read-only reader for the ENC-0f qualification record at
+ * <stateDir>/encoder-qualification.json. The computed-blocker + action-gating
+ * functions live in setup-cortex-blockers.ts (Worker A's canonical module).
+ *
+ * Reader-only: local filesystem read only (PREVENT-PI-004), no `any`
+ * (PREVENT-011), never payloads/prompts/ledger (EVAL-REDACT-002).
+ */
+
+import { homedir } from "node:os";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { QualificationV1 } from "../../src/vector-cortex/encoder/qualify.js";
+import { QUALIFICATION_RECORD_UNAVAILABLE } from "../../src/vector-cortex/setup-cortex-blockers-compute.js";
+
+/** Sentinel appended to thresholdFailures when no valid record is readable (canonical def in setup-cortex-blockers-compute). */
+export { QUALIFICATION_RECORD_UNAVAILABLE };
+
+/**
+ * Resolve the encoder state dir (the record's home) — same precedence as
+ * scripts/encoder/gate-qualify.mjs: MEGACOMPACT_STATE_DIR first, else
+ * ~/.pi/mega-compact-encoder.
+ */
+export function encoderStateDir(): string {
+  const env = process.env.MEGACOMPACT_STATE_DIR;
+  return env !== undefined && env.length > 0
+    ? env
+    : join(homedir(), ".pi", "mega-compact-encoder");
+}
+
+/**
+ * Read + minimally validate the QualificationV1 record. Returns null on a
+ * missing/unreadable file, a JSON parse failure, or a shape mismatch (the
+ * route degrades to verify-only — never crashes). Read-only (PREVENT-PI-004).
+ */
+export function readQualificationRecord(stateDir: string): QualificationV1 | null {
+  let raw: string;
+  try {
+    // guardrails-allow PREVENT-PI-004: local qualification-record filesystem read (loopback)
+    raw = readFileSync(join(stateDir, "encoder-qualification.json"), "utf8");
+  } catch {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw) as unknown;
+  } catch {
+    return null;
+  }
+  const rec = parsed as Record<string, unknown> | null;
+  if (rec === null || typeof rec !== "object") return null;
+  if (rec["schema"] !== "qualification-v1") return null;
+  if (typeof rec["verdict"] !== "string") return null;
+  if (!Array.isArray(rec["reasons"])) return null;
+  if (typeof rec["platform"] !== "string") return null;
+  const reasons = rec["reasons"].map((r) => String(r));
+  return {
+    schema: "qualification-v1",
+    verdict: rec["verdict"] === "qualified" ? "qualified" : "failed",
+    reasons,
+    platform: rec["platform"],
+    p95Ms: typeof rec["p95Ms"] === "number" ? rec["p95Ms"] : 0,
+    rssMib: typeof rec["rssMib"] === "number" ? rec["rssMib"] : 0,
+    opset: typeof rec["opset"] === "number" ? rec["opset"] : 0,
+    digest: typeof rec["digest"] === "string" ? rec["digest"] : "",
+  };
+}
+

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

@@ -288,5 +288,17 @@ export const VECTOR_CORTEX_SETTINGS: SettingGroup = {
 			"ENC-0f p95 + marginal-RSS qualification gate (real trained asset → mode A): runs the ENC-0d-promoted trained asset through the bench under --expose-gc, asserts p95 ≤ 40 ms @ 512/4 threads, marginal RSS ≤ 150 MiB (baseline-subtracted), determinism, and opset-21; on pass emits QualificationV1 + flips runtime to qualified mode A, on failure asset stays demoted to mode B. OFF = no qualification gate runs, no QualificationV1 written, runtime keeps serving the ENC-0d survivor (byte-identical predecessor).",
 			true,
 		),
+		boolDirect(
+			"MEGACOMPACT_ENC_0G",
+			"ENC-0g Setup Cortex honest state (verdict override + live blockers)",
+			"ENC-0g makes the Setup Cortex status route honest: reads the ENC-0f QualificationV1 record (when ENC_0F is ON and a record exists) and lets its verdict override the structural verify for the qualification field; computes the blocker list from (platform, record, manifest head-count) with corrected HG statuses/wording; re-derives VC9B action gating from live blockers. OFF = verdict from verifyEncoderAsset alone, static SETUP_CORTEX_BLOCKERS, static action gating (byte-identical ENC-0f predecessor).",
+			true,
+		),
+		boolDirect(
+			"MEGACOMPACT_ENC_1A",
+			"ENC-1a external embedder API key + endpoint Settings fields",
+			"ENC-1a adds a Settings-visible field pair for the external embedder endpoint URL + optional Bearer API key, persisted by the setup-configure writer branch to the per-repo .mega-compact.env (MEGACOMPACT_EMBEDDING_URL / MEGACOMPACT_EMBEDDING_KEY). The GET status route echoes the endpoint URL and reports embeddingApiKeySet as a boolean ONLY — the raw key is never returned. OFF = no new GET fields, no writer branch, no new Settings text rows (byte-identical ENC-0g predecessor).",
+			true,
+		),
 	],
 };

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

@@ -19,10 +19,18 @@
  */
 
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import type { RouteContext } from "./routes-core.js";
 import { sendJson, readJsonBody } from "./routes-vector-cortex-shared.js";
-import { VC9B_ENABLED } from "../../src/config.js";
-import { setupCortexActionBlockers } from "./setup-cortex-blockers.js";
+import { VC9B_ENABLED, ENC_0G_ENABLED, ENC_0F_ENABLED } from "../../src/config.js";
+import { setupCortexActionBlockers, computeSetupCortexBlockers } from "./setup-cortex-blockers.js";
+import { readEncoderManifest, detectPlatform } from "../../src/vector-cortex/encoder/asset.js";
+import {
+  readQualificationRecord,
+  encoderStateDir,
+} from "./qualification-record.js";
 import {
   runSetupCortexAction,
   readActionLogTail,
@@ -39,6 +47,42 @@ function isActionKind(v: unknown): v is SetupCortexActionKind {
   return typeof v === "string" && ACTION_KINDS.has(v as SetupCortexActionKind);
 }
 
+/** The encoder asset dir used by the action gate (mirrors routes-setup-cortex.ts). */
+function encoderAssetDir(): string | null {
+  let dir = dirname(fileURLToPath(import.meta.url));
+  const rel = join("assets", "vector-cortex", "encoder-v1");
+  for (let i = 0; i < 8; i++) {
+    const candidate = join(dir, rel);
+    if (existsSync(join(candidate, "manifest.json"))) return candidate;
+    const next = dirname(dir);
+    if (next === dir) break;
+    dir = next;
+  }
+  return null;
+}
+
+/**
+ * ENC-0g: the live computed blockers for the action gate. When both gates are
+ * ON, read the QualificationV1 record + verified manifest head-count and derive
+ * the live list (so a closed HG-1 no longer gates fetch-model/bench). Otherwise
+ * return null and let setupCortexActionBlockers fall back to the static base.
+ */
+function liveActionBlockers(): ReturnType<typeof computeSetupCortexBlockers> | null {
+  if (!ENC_0G_ENABLED() || !ENC_0F_ENABLED()) return null;
+  const record = readQualificationRecord(encoderStateDir());
+  let headCount: number | null = null;
+  const dir = encoderAssetDir();
+  if (dir !== null) {
+    const manifest = readEncoderManifest(dir);
+    if (manifest !== null) headCount = Object.keys(manifest.heads).length;
+  }
+  return computeSetupCortexBlockers({
+    platform: detectPlatform(),
+    qualification: record,
+    headCount,
+  });
+}
+
 /** Flag-off response, byte-identical regardless of request (VC9B absent). */
 function sendDisabled(res: ServerResponse): void {
   sendJson(res, 404, { error: "disabled" });
@@ -79,7 +123,10 @@ export function handleSetupCortexAction(
     }
     // Hard-gate check: when an OPEN hard-gate item gates this action, do NOT
     // spawn — surface the blocker ids so the client highlights the matching rows.
-    const blockers = setupCortexActionBlockers(action);
+    // ENC-0g: re-derive against the LIVE computed blockers (a closed HG-1 no
+    // longer blocks), falling back to the static base when the gates are off.
+    const live = liveActionBlockers();
+    const blockers = live !== null ? setupCortexActionBlockers(action, live) : setupCortexActionBlockers(action);
     if (blockers.length > 0) {
       sendJson(res, 423, {
         error: "action_blocked_by_open_item",

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

@@ -25,12 +25,18 @@ import { readFileSync, statSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { RouteContext } from "./routes-core.js";
-import { VC9A_ENABLED, ENC_0E_ENABLED } from "../../src/config.js";
+import { VC9A_ENABLED, ENC_0E_ENABLED, ENC_0F_ENABLED, ENC_0G_ENABLED } from "../../src/config.js";
 import { readEncoderManifest, verifyEncoderAsset, detectPlatform } from "../../src/vector-cortex/encoder/asset.js";
+import type { QualificationV1 } from "../../src/vector-cortex/encoder/qualify.js";
 import { selectRuntimeBackend } from "../../src/vector-cortex/encoder/runtime-select.js";
 import { sendJson } from "./routes-vector-cortex-shared.js";
 import { deriveVcStatus } from "./vc-status.js";
-import { SETUP_CORTEX_BLOCKERS } from "./setup-cortex-blockers.js";
+import { SETUP_CORTEX_BLOCKERS, computeSetupCortexBlockers } from "./setup-cortex-blockers.js";
+import {
+  readQualificationRecord,
+  encoderStateDir,
+  QUALIFICATION_RECORD_UNAVAILABLE,
+} from "./qualification-record.js";
 import type {
   SetupCortexStatusResponse,
   BlockerV1,
@@ -62,6 +68,8 @@ interface SetupCortexFacts {
   assetDigestPrefix: string | null;
   verdict: "qualified" | "demoted" | "unavailable";
   thresholdFailures: string[];
+  /** Number of projection heads the verified manifest declares, or null. */
+  headCount: number | null;
 }
 
 interface SetupCortexFactCache {
@@ -72,7 +80,13 @@ interface SetupCortexFactCache {
 let factCache: SetupCortexFactCache | null = null;
 
 /** Stable cache key: manifest bytes + (size,mtime) of the asset files + platform. */
-function factCacheKey(dir: string, manifestPath: string): string | null {
+function factCacheKey(
+  dir: string,
+  manifestPath: string,
+  stateDir: string,
+  record: QualificationV1 | null,
+  recordGate: boolean,
+): string | null {
   const platform = detectPlatform();
   if (!platform) return null;
   const parts: string[] = [platform];
@@ -86,16 +100,56 @@ function factCacheKey(dir: string, manifestPath: string): string | null {
   } catch {
     return null;
   }
+  // ENC-0g: fold the qualification-record gate + (mtime, content sha) into the
+  // key so a re-run gate invalidates memoized facts (no stale verdict served).
+  try {
+    const s = statSync(join(stateDir, "encoder-qualification.json"));
+    parts.push(`g:${recordGate ? "on" : "off"}`, `q:${s.size}:${s.mtimeMs}`);
+    parts.push(createHash("sha256").update(JSON.stringify(record)).digest("hex"));
+  } catch {
+    parts.push(`g:${recordGate ? "on" : "off"}`, "q:absent");
+  }
   return parts.join("|");
 }
 
-function computeSetupCortexFacts(dir: string): SetupCortexFacts | null {
+function applyQualificationOverride(
+  base: SetupCortexFacts,
+  record: QualificationV1 | null,
+  recordGate: boolean,
+): SetupCortexFacts {
+  // Flag-off (recordGate false): byte-identical verify-derived facts.
+  if (!recordGate) return base;
+  if (record !== null) {
+    // The ENC-0f QualificationV1 failure maps onto the contract "demoted": a
+    // structurally-valid asset whose real-asset gate measured failure is honest
+    // as demoted, NOT qualified. mode stays verify-derived (A).
+    return {
+      ...base,
+      verdict: record.verdict === "qualified" ? "qualified" : "demoted",
+      thresholdFailures: [...record.reasons],
+    };
+  }
+  // No record + gate on: keep the verify verdict but surface the missing-record
+  // sentinel (never a fabricated pass, never a bare silent fallback).
+  return {
+    ...base,
+    thresholdFailures: [...base.thresholdFailures, QUALIFICATION_RECORD_UNAVAILABLE],
+  };
+}
+
+function computeSetupCortexFacts(
+  dir: string,
+  stateDir: string,
+  record: QualificationV1 | null,
+  recordGate: boolean,
+): SetupCortexFacts | null {
   const manifest = readEncoderManifest(dir);
   if (manifest === null) {
-    return { mode: "C", assetDigestPrefix: null, verdict: "unavailable", thresholdFailures: [] };
+    return { mode: "C", assetDigestPrefix: null, verdict: "unavailable", thresholdFailures: [], headCount: null };
   }
+  const headCount = Object.keys(manifest.heads).length;
   const manifestPath = join(dir, "manifest.json");
-  const key = factCacheKey(dir, manifestPath);
+  const key = factCacheKey(dir, manifestPath, stateDir, record, recordGate);
   if (key === null) return null;
   if (factCache !== null && factCache.key === key) return factCache.facts;
   let digest: string;
@@ -103,26 +157,31 @@ function computeSetupCortexFacts(dir: string): SetupCortexFacts | null {
     // guardrails-allow PREVENT-PI-004: local manifest filesystem read (loopback)
     digest = createHash("sha256").update(readFileSync(manifestPath)).digest("hex");
   } catch {
-    const facts: SetupCortexFacts = { mode: "B", assetDigestPrefix: null, verdict: "demoted", thresholdFailures: ["ENC_ASSET_UNREADABLE"] };
+    const base: SetupCortexFacts = { mode: "B", assetDigestPrefix: null, verdict: "demoted", thresholdFailures: ["ENC_ASSET_UNREADABLE"], headCount };
+    const facts = applyQualificationOverride(base, record, recordGate);
     factCache = { key, facts };
     return facts;
   }
   const verify = verifyEncoderAsset(dir, manifest, detectPlatform());
   const prefix = digest.slice(0, 12);
-  const facts: SetupCortexFacts = verify.ok
-    ? { mode: "A", assetDigestPrefix: prefix, verdict: "qualified", thresholdFailures: [] }
-    : { mode: "B", assetDigestPrefix: prefix, verdict: "demoted", thresholdFailures: [verify.code] };
+  const base: SetupCortexFacts = verify.ok
+    ? { mode: "A", assetDigestPrefix: prefix, verdict: "qualified", thresholdFailures: [], headCount }
+    : { mode: "B", assetDigestPrefix: prefix, verdict: "demoted", thresholdFailures: [verify.code], headCount };
+  const facts = applyQualificationOverride(base, record, recordGate);
   factCache = { key, facts };
   return facts;
 }
 
-function setupCortexFacts(): SetupCortexFacts {
+function setupCortexFacts(
+  record: QualificationV1 | null,
+  recordGate: boolean,
+): SetupCortexFacts {
   const dir = encoderAssetDir();
   if (dir === null) {
-    return { mode: "C", assetDigestPrefix: null, verdict: "unavailable", thresholdFailures: [] };
+    return { mode: "C", assetDigestPrefix: null, verdict: "unavailable", thresholdFailures: [], headCount: null };
   }
-  const facts = computeSetupCortexFacts(dir);
-  return facts ?? { mode: "C", assetDigestPrefix: null, verdict: "unavailable", thresholdFailures: [] };
+  const facts = computeSetupCortexFacts(dir, encoderStateDir(), record, recordGate);
+  return facts ?? { mode: "C", assetDigestPrefix: null, verdict: "unavailable", thresholdFailures: [], headCount: null };
 }
 
 /**
@@ -145,8 +204,25 @@ export function handleSetupCortexStatus(
   }
 
   const enabled = VC9A_ENABLED();
-  const facts = enabled ? setupCortexFacts() : null;
-  const blocks: BlockerV1[] = enabled ? [...SETUP_CORTEX_BLOCKERS] : [];
+
+  // ENC-0g: when both gates are ON, read the QualificationV1 record and let its
+  // verdict override the structural verify for the `qualification` field. When
+  // ENC_0G is OFF, nothing below reads the record (byte-identical to ENC-0f-era).
+  const enc0g = enabled && ENC_0G_ENABLED();
+  const recordGate = enc0g && ENC_0F_ENABLED();
+  const record = recordGate ? readQualificationRecord(encoderStateDir()) : null;
+
+  const facts = enabled ? setupCortexFacts(record, recordGate) : null;
+
+  const blocks: BlockerV1[] = enabled
+    ? enc0g
+      ? [...computeSetupCortexBlockers({
+          platform: detectPlatform(),
+          qualification: record,
+          headCount: facts ? facts.headCount : null,
+        })]
+      : [...SETUP_CORTEX_BLOCKERS]
+    : [];
 
   // ENC-0e: surface the darwin-x64 demotion reason additively (reader-only GET,
   // no new route). The platform is read locally; the selection is pure. On a

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

@@ -0,0 +1,184 @@
+/**
+ * dashboard-server/routes-setup-enc1a.ts — ENC-1a external-embedder Settings
+ * read/write + the additive writer branch.
+ *
+ * Extracted out of routes-setup.ts (which hovers at the 300-line source soft
+ * cap) so the ENC-1a additive read/write of the per-repo `.mega-compact.env`
+ * keys AND the pure external-embedder configure branch live in a sibling impl
+ * file. The two keys are `MEGACOMPACT_EMBEDDING_URL` and
+ * `MEGACOMPACT_EMBEDDING_KEY` — the exact names `embeddingConfigFromEnv`
+ * (src/httpEmbedder.ts) reads at runtime.
+ *
+ * The write is create-or-append: it upserts the two keys into the existing
+ * per-repo `.mega-compact.env`, preserving every unrelated line and never
+ * deleting other keys. The read reports the endpoint URL (echoed) and an
+ * `apiKeySet` boolean ONLY — the raw API key is never returned, logged, or
+ * emitted (redaction invariant).
+ *
+ * Guardrails: PREVENT-PI-004 (local filesystem writes only, zero network),
+ * PREVENT-001 (null-safe JSON), PREVENT-011 (no `any`).
+ */
+
+import { writeFileSync, mkdirSync, readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import type { ServerResponse } from "node:http";
+import type { RouteContext } from "./routes-core.js";
+import { ENC_1A_ENABLED } from "../../src/config.js";
+import type {
+	SetupConfigureRequest,
+	SetupConfigureResponse,
+} from "./api-contracts/setup.js";
+
+const URL_KEY = "MEGACOMPACT_EMBEDDING_URL";
+const API_KEY = "MEGACOMPACT_EMBEDDING_KEY";
+
+function envPath(stateDir: string): string {
+	return join(stateDir, ".mega-compact.env");
+}
+
+/** Extract the value of `export MEGACOMPACT_X="..."` (or unquoted) from a line. */
+function lineValue(line: string, key: string): string | null {
+	const m = line.match(new RegExp(`^export\\s+${key}=(.*)$`));
+	if (!m) return null;
+	const rest = m[1].trim();
+	const q = rest.match(/^"([^"]*)"$/);
+	return q ? q[1] : rest;
+}
+
+/** True when the payload carries the ENC-1a keys (flag-gated). */
+export function wantsEnc1a(body: SetupConfigureRequest): boolean {
+	return (
+		ENC_1A_ENABLED() &&
+		(typeof body.embeddingEndpointUrl === "string" ||
+			typeof body.embeddingApiKey === "string")
+	);
+}
+
+/** Additive GET status fields for ENC-1a (both omitted when flag-off): the
+ *  endpoint URL (echoed) + an apiKeySet boolean (true/false) ONLY — never the
+ *  raw key. The boolean is always present when the flag is on so an absent key
+ *  is reported as `embeddingApiKeySet:false` (non-fatal, triad B). */
+export function enc1aStatusFields(stateDir: string): {
+	embeddingEndpointUrl?: string;
+	embeddingApiKeySet?: boolean;
+} {
+	if (!ENC_1A_ENABLED()) return {};
+	const enc1a = readEnc1aEnv(stateDir);
+	return {
+		...(enc1a.endpointUrl !== null ? { embeddingEndpointUrl: enc1a.endpointUrl } : {}),
+		embeddingApiKeySet: enc1a.apiKeySet,
+	};
+}
+
+/** Read the ENC-1a keys from the per-repo `.mega-compact.env` (never the key
+ *  itself to callers — only its presence). */
+export function readEnc1aEnv(stateDir: string): {
+	endpointUrl: string | null;
+	apiKeySet: boolean;
+} {
+	try {
+		const p = envPath(stateDir);
+		if (!existsSync(p)) return { endpointUrl: null, apiKeySet: false };
+		const content = readFileSync(p, "utf8");
+		const lines = content.split(/\r?\n/);
+		let endpointUrl: string | null = null;
+		let apiKeySet = false;
+		for (const line of lines) {
+			const url = lineValue(line, URL_KEY);
+			if (url !== null) endpointUrl = url;
+			const key = lineValue(line, API_KEY);
+			if (key !== null && key.length > 0) apiKeySet = true;
+		}
+		return { endpointUrl, apiKeySet };
+	} catch {
+		return { endpointUrl: null, apiKeySet: false };
+	}
+}
+
+/** Upsert the ENC-1a keys into the per-repo `.mega-compact.env`. Creates the
+ *  file if absent; preserves every unrelated line; never deletes other keys.
+ *  Passing `null` for a key leaves that line untouched. */
+export function writeEnc1aEnv(
+	stateDir: string,
+	entries: { endpointUrl?: string | null; apiKey?: string | null },
+): string {
+	const p = envPath(stateDir);
+	const existingLines: string[] = existsSync(p)
+		? readFileSync(p, "utf8").split(/\r?\n/)
+		: [];
+	const out: string[] = [];
+	let urlWritten = false;
+	let keyWritten = false;
+	for (const line of existingLines) {
+		if (entries.endpointUrl !== null && lineValue(line, URL_KEY) !== null) {
+			out.push(`export ${URL_KEY}="${entries.endpointUrl ?? ""}"`);
+			urlWritten = true;
+			continue;
+		}
+		if (entries.apiKey !== null && lineValue(line, API_KEY) !== null) {
+			out.push(`export ${API_KEY}="${entries.apiKey ?? ""}"`);
+			keyWritten = true;
+			continue;
+		}
+		out.push(line);
+	}
+	if (entries.endpointUrl !== null && !urlWritten) {
+		out.push(`export ${URL_KEY}="${entries.endpointUrl}"`);
+	}
+	if (entries.apiKey !== null && !keyWritten) {
+		out.push(`export ${API_KEY}="${entries.apiKey ?? ""}"`);
+	}
+	mkdirSync(stateDir, { recursive: true });
+	writeFileSync(p, out.join("\n"), "utf-8");
+	return p;
+}
+
+/** If the payload is a pure ENC-1a configure (new keys, no valid embedder
+ *  selection), write them additively to the per-repo env and reply. Returns
+ *  true when it fully handled the request. */
+export function tryEnc1aConfigure(
+	body: SetupConfigureRequest,
+	res: ServerResponse,
+	ctx: RouteContext,
+): boolean {
+	if (!wantsEnc1a(body)) return false;
+	const embedder = body.embedder;
+	const embedderValid =
+		!!embedder &&
+		(embedder === "ollama" || embedder === "llama" || embedder === "trigram" ||
+			embedder === "custom" || embedder === "onnx");
+	if (embedderValid) return false; // combined payload — integrated after the embedder write
+	try {
+		const envPath = writeEnc1aEnv(ctx.stateDir, {
+			endpointUrl:
+				typeof body.embeddingEndpointUrl === "string" && body.embeddingEndpointUrl
+					? body.embeddingEndpointUrl
+					: null,
+			apiKey: typeof body.embeddingApiKey === "string" ? body.embeddingApiKey : null,
+		});
+		const currentUrl = process.env["MEGACOMPACT_EMBEDDING_URL"];
+		const alreadyActive =
+			typeof body.embeddingEndpointUrl === "string" &&
+			currentUrl === body.embeddingEndpointUrl;
+		const resp: SetupConfigureResponse = {
+			embedder: "custom",
+			url:
+				typeof body.embeddingEndpointUrl === "string"
+					? body.embeddingEndpointUrl
+					: null,
+			envPath,
+			restartRequired: !alreadyActive,
+			alreadyActive,
+		};
+		// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+		res.writeHead(200, { "Content-Type": "application/json" });
+		res.end(JSON.stringify(resp));
+		return true;
+	} catch (e) {
+		res.writeHead(500, { "Content-Type": "application/json" });
+		res.end(
+			JSON.stringify({ error: `write_failed: ${e instanceof Error ? e.message : String(e)}` }),
+		);
+		return true;
+	}
+}

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

@@ -14,6 +14,7 @@ import { join } from "node:path";
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { RouteContext } from "./routes-core.js";
 import { VC9D_ENABLED } from "../../src/config.js";
+import { enc1aStatusFields, writeEnc1aEnv, tryEnc1aConfigure, wantsEnc1a } from "./routes-setup-enc1a.js";
 import {
 	detectOllama,
 	detectLlamaCpp,
@@ -77,6 +78,9 @@ export function handleSetupStatus(
 	}
 	const configured = detectConfiguredEmbedder(ctx.stateDir);
 	const active = detectCurrentEmbedder();
+	// 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 = {
 		currentEmbedder: active,
 		configuredEmbedder: configured.embedder,
@@ -87,6 +91,7 @@ export function handleSetupStatus(
 		minilm: ["1", "true", "yes"].includes(
 			(process.env["MEGACOMPACT_MINILM"] ?? "").trim().toLowerCase(),
 		),
+		...enc1aStatusFields(ctx.stateDir),
 	};
 	// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
 	res.writeHead(200, { "Content-Type": "application/json" });
@@ -205,6 +210,11 @@ export function handleSetupConfigure(
 			return;
 		}
 		const body = parsed.value as unknown as SetupConfigureRequest;
+		// 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 (tryEnc1aConfigure(body, res, ctx)) return;
 		const embedder = body.embedder;
 		if (embedder !== "ollama" && embedder !== "llama" && embedder !== "trigram" && embedder !== "custom" && embedder !== "onnx") {
 			res.writeHead(400, { "Content-Type": "application/json" });
@@ -258,6 +268,17 @@ export function handleSetupConfigure(
 			res.end(JSON.stringify({ error: `write_failed: ${e instanceof Error ? e.message : String(e)}` }));
 			return;
 		}
+		// ENC-1a: a combined payload (valid embedder + new keys) also upserts
+		// the endpoint/key lines onto the freshly-written env file.
+		if (wantsEnc1a(body)) {
+			writeEnc1aEnv(stateDir, {
+				endpointUrl:
+					typeof body.embeddingEndpointUrl === "string" && body.embeddingEndpointUrl
+						? body.embeddingEndpointUrl
+						: null,
+				apiKey: typeof body.embeddingApiKey === "string" ? body.embeddingApiKey : null,
+			});
+		}
 		// Detect if the new config matches what's already active (no restart needed).
 		const currentUrl = process.env["MEGACOMPACT_EMBEDDING_URL"];
 		const alreadyActive = (resolvedUrl === null && !currentUrl) || (resolvedUrl !== null && currentUrl === resolvedUrl);