pi-mega-compact 0.20.25 → 0.20.27

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

@@ -0,0 +1,167 @@
+/**
+ * dashboard-server/routes-setup-cortex.ts — VC9A Setup Cortex status route.
+ *
+ *   GET /api/setup-cortex-status — reader-only aggregate surfacing the
+ *        vector-cortex encoder gate (mode A/B/C, qualification verdict,
+ *        blockers, encoder health) for the dashboard Setup tab. Does NOT close
+ *        the ML gate: the hard-gate blockers are read-only and stay open.
+ *
+ * Reuses readEncoderManifest / verifyEncoderAsset / detectPlatform
+ * (src/vector-cortex/encoder/asset.ts) and deriveVcStatus (vc-status.ts),
+ * plus the memoized encoder-facts pattern from routes-vector-cortex-health.ts
+ * (manifest bytes + file size/mtime + platform cache key) so the expensive
+ * full-asset hashing is skipped on repeat polls.
+ *
+ * The blocker rows carry NO string literals here — they come from the static
+ * manifest module setup-cortex-blockers.ts (single canonical source).
+ *
+ * Guardrails: PREVENT-PI-004 (local filesystem read only), PREVENT-011 (no
+ * `any`), reader-only aggregate (never payloads/prompts/ledger — EVAL-REDACT-002).
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { createHash } from "node:crypto";
+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 } from "../../src/config.js";
+import { readEncoderManifest, verifyEncoderAsset, detectPlatform } from "../../src/vector-cortex/encoder/asset.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 type {
+  SetupCortexStatusResponse,
+  BlockerV1,
+} from "./api-contracts/setup-cortex.js";
+
+/** Resolve the committed encoder-v1 asset dir by walking up to the repo root. */
+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);
+    try {
+      // guardrails-allow PREVENT-PI-004: local asset filesystem read (loopback)
+      readFileSync(join(candidate, "manifest.json"));
+      return candidate;
+    } catch {
+      /* keep walking */
+    }
+    const next = dirname(dir);
+    if (next === dir) break;
+    dir = next;
+  }
+  return null;
+}
+
+/** Reader-only encoder health facts: mode + asset digest (+ vertex/verdict). */
+interface SetupCortexFacts {
+  mode: "A" | "B" | "C";
+  assetDigestPrefix: string | null;
+  verdict: "qualified" | "demoted" | "unavailable";
+  thresholdFailures: string[];
+}
+
+interface SetupCortexFactCache {
+  key: string;
+  facts: SetupCortexFacts;
+}
+
+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 {
+  const platform = detectPlatform();
+  if (!platform) return null;
+  const parts: string[] = [platform];
+  try {
+    for (const p of [manifestPath, join(dir, "model.onnx"), join(dir, "tokenizer.json")]) {
+      const s = statSync(p);
+      parts.push(`${s.size}:${s.mtimeMs}`);
+    }
+    // guardrails-allow PREVENT-PI-004: local manifest filesystem read (loopback)
+    parts.push(createHash("sha256").update(readFileSync(manifestPath)).digest("hex"));
+  } catch {
+    return null;
+  }
+  return parts.join("|");
+}
+
+function computeSetupCortexFacts(dir: string): SetupCortexFacts | null {
+  const manifest = readEncoderManifest(dir);
+  if (manifest === null) {
+    return { mode: "C", assetDigestPrefix: null, verdict: "unavailable", thresholdFailures: [] };
+  }
+  const manifestPath = join(dir, "manifest.json");
+  const key = factCacheKey(dir, manifestPath);
+  if (key === null) return null;
+  if (factCache !== null && factCache.key === key) return factCache.facts;
+  let digest: string;
+  try {
+    // 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"] };
+    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] };
+  factCache = { key, facts };
+  return facts;
+}
+
+function setupCortexFacts(): SetupCortexFacts {
+  const dir = encoderAssetDir();
+  if (dir === null) {
+    return { mode: "C", assetDigestPrefix: null, verdict: "unavailable", thresholdFailures: [] };
+  }
+  const facts = computeSetupCortexFacts(dir);
+  return facts ?? { mode: "C", assetDigestPrefix: null, verdict: "unavailable", thresholdFailures: [] };
+}
+
+/**
+ * Reader-only GET /api/setup-cortex-status (VC9A).
+ *
+ * Purely read: no mutation, never payloads/prompts/ledger. Flag-off returns the
+ * byte-identical VC8C-era shape `{enabled:false, mode:"C", status:"off"}` with
+ * the encoder-health mode C and no qualification/blocker detail leaked.
+ */
+export function handleSetupCortexStatus(
+  req: IncomingMessage,
+  res: ServerResponse,
+  _ctx: RouteContext,
+): boolean {
+  const url = req.url ?? "";
+  if (url !== "/api/setup-cortex-status") return false;
+  if (req.method !== "GET") {
+    sendJson(res, 405, { error: "method_not_allowed" });
+    return true;
+  }
+
+  const enabled = VC9A_ENABLED();
+  const facts = enabled ? setupCortexFacts() : null;
+  const blocks: BlockerV1[] = enabled ? [...SETUP_CORTEX_BLOCKERS] : [];
+
+  const body: SetupCortexStatusResponse = {
+    enabled,
+    flag: "MEGACOMPACT_VC9A",
+    mode: facts ? facts.mode : "C",
+    assetDigestPrefix: facts ? facts.assetDigestPrefix : null,
+    qualification: facts
+      ? { verdict: facts.verdict, thresholdFailures: facts.thresholdFailures }
+      : { verdict: "unavailable", thresholdFailures: [] },
+    blockers: blocks,
+    encoderHealth: facts
+      ? { assetDigestPrefix: facts.assetDigestPrefix, mode: facts.mode }
+      : { assetDigestPrefix: null, mode: "C" },
+    updatedAt: new Date().toISOString(),
+    status: deriveVcStatus({ enabled, hasData: !!facts && facts.verdict !== "unavailable", structuralOnly: true }),
+  };
+  sendJson(res, 200, body);
+  return true;
+}

package/extensions/dashboard-server/routes.ts

@@ -56,3 +56,4 @@ export {
 	handleVectorCortexClosureProof,
 	handleVectorCortexRestore,
 } from "./routes-vector-cortex.js";
+export { handleSetupCortexStatus } from "./routes-setup-cortex.js";

package/extensions/dashboard-server/server.ts

@@ -302,9 +302,11 @@ export async function launchDashboardServer(
 					v6.listen(port, "::1", () => log("ipv6 loopback bound", { port })); // guardrails-allow PREVENT-PI-004: IPv6 loopback (::1) mirror of the dashboard server
 				}
 
-				// Write port.pid
+				// Write port.pid (VC0F B2: stamp `version` so the launcher can detect
+				// a stale runner by comparing the marker against its own version
+				// without an HTTP probe — closes the orphan case for pre-B2 servers).
 				try {
-					writeFileSync(portFile, JSON.stringify({ port, pid: process.pid }));
+					writeFileSync(portFile, JSON.stringify({ port, pid: process.pid, version: SERVER_VERSION }));
 				} catch (e) {
 					log("could not write port.pid", { error: String(e) });
 				}

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

@@ -0,0 +1,73 @@
+/**
+ * dashboard-server/setup-cortex-blockers.ts — canonical blocker manifest for the
+ * dashboard Setup Cortex status read path (VC9A).
+ *
+ * The hard-gate items enumerated in docs/vector-cortex/vc2-model-prep.md §6
+ * (per the 2026-08-05 research update: the opset-14→17 re-export blocker is
+ * REMOVED because onnx-community exports are now opset 21). This module is the
+ * SINGLE canonical source of those blockers — the route file
+ * (routes-setup-cortex.ts) carries NO string literals for them; it reads this
+ * static manifest so the UI rows and the spec stay in one place.
+ *
+ * Reader-only, static: zero network, no writes (PREVENT-PI-004), no `any`
+ * (PREVENT-011).
+ */
+
+/** The open hard-gate items VC9A surfaces (nothing is closed in-workstream). */
+export interface SetupCortexBlockerV1 {
+  /** Stable machine id (e.g. HG-1) the client can key rows on. */
+  readonly id: string;
+  /** Human title shown on the blockers card. */
+  readonly title: string;
+  /** Severity: blocker | high | medium. */
+  readonly severity: "blocker" | "high" | "medium";
+  /** Lifecycle state — all OPEN (hard gates are never silently closed). */
+  readonly status: "open";
+  /** Optional candidate resolution surfaced for the controller / user. */
+  readonly resolution?: string;
+}
+
+/**
+ * The four blockers VC9A reports. Enumerates the vc2-model-prep §6 items that
+ * remain per the 2026-08-05 research. The opset re-export blocker (formerly
+ * §6 #2) is NOT listed: onnx-community exports are opset 21, so it is removed.
+ */
+export const SETUP_CORTEX_BLOCKERS: readonly SetupCortexBlockerV1[] = [
+  {
+    id: "HG-1",
+    title: "Five projection heads do not exist",
+    severity: "blocker",
+    status: "open",
+    resolution:
+      "Supervision transfer onto a frozen bge-small-en-v1.5 trunk (contradiction distilled from cross-encoder/nli-deberta-v3-small; dependency NLI-assisted; cache-stability deterministic; payload-routing small MLP) — VC2B training + export.",
+  },
+  {
+    id: "HG-3",
+    title: "onnxruntime-node install exceeds the 80 MiB asset budget",
+    severity: "blocker",
+    status: "open",
+    resolution:
+      "onnxruntime-node bundles ~258 MiB across all platforms. Candidate: transformers.js v4.2.0 (9.5 MiB shell, pure-Node via onnxruntime-web WASM) measured against budget + p95 gate before committing.",
+  },
+  {
+    id: "HG-4",
+    title: "No darwin-x64 binary in onnxruntime-node",
+    severity: "high",
+    status: "open",
+    resolution:
+      "Intel-Mac mode-A users demote to the WASM path (if HG-3 resolves that way) or mode B.",
+  },
+  {
+    id: "HG-5",
+    title: "RSS margin at 512 tokens is ~0.5%",
+    severity: "medium",
+    status: "open",
+    resolution:
+      "149.2 MiB vs 150 MiB cap with run-to-run variance 119-149 MiB; considers capping mode A at 384 tokens or using the marginal-footprint accounting runtime.ts already implements.",
+  },
+];
+
+/** Look up one blocker by id; undefined when unknown (defensive). */
+export function setupCortexBlocker(id: string): SetupCortexBlockerV1 | undefined {
+  return SETUP_CORTEX_BLOCKERS.find((b) => b.id === id);
+}

package/extensions/mega-dashboard-bounce.ts

@@ -0,0 +1,97 @@
+/**
+ * mega-dashboard-bounce.ts — VC0F stale-runner detection + bounce.
+ *
+ * Delegate of `mega-dashboard-cmds.ts` (kept under the extensions/ soft limit):
+ * owns the once-per-process staleness gate and the pure
+ * `bounceStaleRunnerIfAny` decision, which is the durable restart-on-upgrade
+ * seam — after `pi update --extensions` replaces the on-disk package, the next
+ * `session_start` probes the running dashboard, sees the version mismatch, and
+ * kills + respawns the stale runner so it serves the current code.
+ *
+ * The function is dependency-injected so unit tests (VC0F C1–C3) can stub every
+ * primitive; the production wiring (live discovery / version / kill) lives in
+ * `mega-dashboard-cmds.ts` and is passed in. No network here — the localhost
+ * HTTP probes live behind the injected `isServerRunning`/`serverVersion` deps
+ * (already audited PREVENT-PI-004 in the parent file).
+ */
+
+/**
+ * Once-per-process staleness gate (VC0F A2). After the FIRST successful probe
+ * we skip re-probing on later /mega-dashboard invocations or session-start
+ * events within the same extension process — the probe is cheap but the
+ * kill+respawn it triggers is disruptive. Set regardless of outcome.
+ */
+let stalenessCheckedThisProcess = false;
+
+/** Test-only seam: clear the once-per-process gate between unit tests. */
+export function resetStalenessGateForTests(): void {
+  stalenessCheckedThisProcess = false;
+}
+
+/** Injectables `bounceStaleRunnerIfAny` needs from the current repo's dashboard
+ *  lifecycle. Injected so the unit tests (VC0F C1–C3) can stub each primitive
+ *  independently. */
+export interface BounceStaleDeps {
+  /** Discover a live dashboard server for the current repo, or null. */
+  isServerRunning(): Promise<{ port: number; url: string; hasPidFile: boolean } | null>;
+  /** Version the running server reports via HTTP (/api/version), or null. */
+  serverVersion(port: number): Promise<string | null>;
+  /** Version stamped in the current repo's port.pid marker, or null. */
+  markerVersion(): string | null;
+  /** Version of THIS extension package (from its own package.json). */
+  ownVersion(): string | null;
+  /** Kill the server on `port` and clear its marker (best-effort). */
+  killServerOnPort(port: number): void;
+  /** User notification; a no-op on the silent session-start path (VC0F A3). */
+  notify(message: string): void;
+}
+
+/**
+ * Detect + replace a STALE dashboard runner for the current repo (VC0F A1).
+ *
+ * A runner is stale when it is an orphan (live but missing its port.pid
+ * marker), when its marker's stamped `version` differs from this extension's
+ * own version (VC0F B2 — avoids the HTTP probe), or when the version it
+ * reports over HTTP differs from our own (fallback for pre-B2 servers whose
+ * marker has no `version` field). A stale runner is killed so the next launch
+ * serves the current on-disk code.
+ *
+ * Best-effort and non-fatal (Goal 4): any failure returns `{bounced:false}`
+ * and never throws. Runs at most once per extension process (A2).
+ */
+export async function bounceStaleRunnerIfAny(deps: BounceStaleDeps): Promise<{ bounced: boolean }> {
+  if (stalenessCheckedThisProcess) return { bounced: false };
+  try {
+    stalenessCheckedThisProcess = true; // once per process, regardless of outcome
+    const info = await deps.isServerRunning();
+    if (!info) return { bounced: false };
+    const orphan = !info.hasPidFile;
+    const want = deps.ownVersion();
+    const marker = deps.markerVersion();
+    let stale: boolean;
+    let from: string | null = null;
+    if (orphan) {
+      stale = true; // live server with no marker → orphan by definition
+    } else if (want != null && marker != null) {
+      stale = marker !== want; // B2: compare the stamped marker, skip the HTTP probe
+      from = marker;
+    } else {
+      const running = await deps.serverVersion(info.port);
+      from = running;
+      stale = want != null && running != null && running !== want;
+    }
+    if (stale) {
+      deps.notify(
+        orphan
+          ? "[mega-compact] replacing orphaned dashboard server…"
+          : `[mega-compact] replacing stale dashboard (${from ?? "?"} → ${want ?? "?"})…`,
+      );
+      deps.killServerOnPort(info.port);
+      return { bounced: true };
+    }
+    return { bounced: false };
+  } catch {
+    // Best-effort, non-fatal — a failed probe/kill never breaks the caller.
+    return { bounced: false };
+  }
+}

package/extensions/mega-dashboard-cmds.ts

@@ -12,6 +12,15 @@ import { fileURLToPath } from "node:url";
 import { existsSync, writeFileSync, readFileSync, unlinkSync, openSync, closeSync } from "node:fs";
 import { spawn, execSync } from "node:child_process"; // guardrails-allow PREVENT-PI-004: spawns the optional, user-triggered localhost dashboard server only
 import type { MegaRuntime } from "./mega-runtime.js";
+import {
+  bounceStaleRunnerIfAny,
+  type BounceStaleDeps,
+} from "./mega-dashboard-bounce.js";
+
+// Re-export the VC0F bounce seam for the unit tests, which import the parent
+// module. The implementation + once-per-process gate live in the sibling
+// delegate file to keep this module under the extensions/ soft limit (400).
+export { bounceStaleRunnerIfAny, resetStalenessGateForTests, type BounceStaleDeps } from "./mega-dashboard-bounce.js";
 
 /** Register the dashboard server lifecycle commands. */
 export function registerDashboardCommands(pi: ExtensionAPI, runtime: MegaRuntime): void {
@@ -111,6 +120,28 @@ export function registerDashboardCommands(pi: ExtensionAPI, runtime: MegaRuntime
     try { unlinkSync(portFile()); } catch { /* ignore */ }
   }
 
+  /** Version stamped in the current repo's port.pid marker (VC0F B2), or null
+   *  when the marker is absent or predates the stamped `version` field. */
+  function markerVersion(): string | null {
+    try {
+      const info = JSON.parse(readFileSync(portFile(), "utf-8")) as { version?: unknown };
+      return typeof info.version === "string" ? info.version : null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Build the dependency set `bounceStaleRunnerIfAny` needs for the CURRENT
+   * repo's dashboard lifecycle (port.pid / runner / launch-log all resolve via
+   * `runtime.currentStateDir`, so a repo switch re-targets the bounce).
+   * `notify` is threaded here so the interactive /mega-dashboard path surfaces
+   * the replace messages while the silent session-start path is a no-op.
+   */
+  function staleBounceDeps(notify: (msg: string) => void): BounceStaleDeps {
+    return { isServerRunning, serverVersion, markerVersion, ownVersion, killServerOnPort, notify };
+  }
+
   /**
    * Resolve the launchable dashboard-server module.
    *
@@ -148,9 +179,14 @@ export function registerDashboardCommands(pi: ExtensionAPI, runtime: MegaRuntime
     const resolved = resolveDashboardEntry();
     if (!resolved) return false;
     dashboardNeedsStrip = resolved.needsStripTypes;
+    // VC0F B1: stamp the extension version in the generated script at WRITE time
+    // so a future probe can compare it against ownVersion() without a live HTTP
+    // round-trip (useful when the server is hung and /api/version times out).
+    const stampedVersion = ownVersion() ?? "0.0.0";
     const script = [
       `import { appendFileSync } from "node:fs";`,
       `const __log = ${JSON.stringify(launchLog())};`,
+      `const __VERSION = ${JSON.stringify(stampedVersion)}; // mega-compact bundle version stamped at write time (VC0F B1)`,
       `function __fail(err) {`,
       `  const msg = "[mega-compact] dashboard failed: " + (err && err.stack ? err.stack : String(err));`,
       `  try { appendFileSync(__log, msg + "\\n"); } catch { /* ignore */ }`,
@@ -181,32 +217,18 @@ export function registerDashboardCommands(pi: ExtensionAPI, runtime: MegaRuntime
     description: "Start the local web dashboard and optionally open it in the default browser.",
     handler: async (_args: string, ctx: ExtensionContext) => {
       runtime.bindRepo(ctx.cwd);
-      let info = await isServerRunning();
+      // VC0F A1: lift the stale-replace decision out of the handler. Interactive
+      // path is unchanged — the user is still notified before a stale runner is
+      // killed. When a stale server is bounced, we fall straight through to a
+      // fresh spawn; otherwise reuse the live current server if there is one.
+      const { bounced } = await bounceStaleRunnerIfAny(staleBounceDeps((msg) => ctx.ui.notify(msg)));
+      const info = bounced ? null : await isServerRunning();
 
       if (info) {
-        // Replace the server when it's stale: either (a) an orphan — a live
-        // server with no port.pid (e.g. left running from a detached spawn or a
-        // previous upgrade) that keeps serving old HTML from memory; or (b) a
-        // server that reports a different version than this extension (an older
-        // build). A live server WITH a matching pid file and version is reused.
-        const orphan = !info.hasPidFile;
-        const running = await serverVersion(info.port);
-        const want = ownVersion();
-        const stale = orphan || (want != null && running != null && running !== want);
-        if (stale) {
-          ctx.ui.notify(
-            orphan
-              ? "[mega-compact] replacing orphaned dashboard server…"
-              : `[mega-compact] replacing stale dashboard (${running} → ${want})…`,
-          );
-          killServerOnPort(info.port);
-          info = null;
-        } else {
-          ctx.ui.notify(`[mega-compact] dashboard already running at ${info.url}`);
-          const open = await ctx.ui.confirm("mega-compact dashboard", `Open ${info.url} in browser?`);
-          if (open) openBrowser(info.url);
-          return;
-        }
+        ctx.ui.notify(`[mega-compact] dashboard already running at ${info.url}`);
+        const open = await ctx.ui.confirm("mega-compact dashboard", `Open ${info.url} in browser?`);
+        if (open) openBrowser(info.url);
+        return;
       }
 
       // Start the server
@@ -310,4 +332,21 @@ export function registerDashboardCommands(pi: ExtensionAPI, runtime: MegaRuntime
       }
     },
   });
+
+  // VC0F A3 — durable restart-on-upgrade: after `pi update --extensions`
+  // replaces the on-disk package, the next pi session probes the running
+  // dashboard, sees the version mismatch, and kills + respawns the stale runner
+  // automatically. SILENT — no ctx.ui.notify on this session-start path (unlike
+  // the explicit /mega-dashboard path). Best-effort and non-fatal: a probe or
+  // kill failure here never breaks session startup.
+  pi.on("session_start", async (_event, ctx) => {
+    runtime.bindRepo(ctx.cwd);
+    try {
+      await bounceStaleRunnerIfAny(
+        staleBounceDeps(() => { /* session-start path stays silent (VC0F A3) */ }),
+      );
+    } catch {
+      /* best-effort — never break the session */
+    }
+  });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.20.25",
+  "version": "0.20.27",
   "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-vc9a.ts

@@ -0,0 +1,31 @@
+/**
+ * config/vector-cortex-vc9a.ts — VC9A setup-cortex status-read-path sprint flag.
+ *
+ * Extracted from vector-cortex.ts so that file stays under the 300-line soft
+ * limit (soft-as-hard gate), exactly as vector-cortex-vc8c.ts,
+ * vector-cortex-breakers.ts and vector-cortex-early.ts were. This is the
+ * SETUP-DASHBOARD reader flag (the dashboard Setup tab cortex status endpoint).
+ * vector-cortex.ts re-exports it below and root src/config.ts re-exports it, so
+ * no consumer import path changes.
+ *
+ * The split is purely mechanical: VC9A_ENABLED is byte-identical in name,
+ * semantics, and default to the definition it replaces, and vector-cortex.ts
+ * re-exports it so every existing `from "./config/vector-cortex.js"` import
+ * keeps resolving unchanged.
+ *
+ * Pi-agnostic, dependency-free (PREVENT-PI-004 / PREVENT-011).
+ */
+
+import { sprintFlag } from "./vector-cortex-flag.js";
+
+/**
+ * VC9A — Setup Cortex status read path (GET /api/setup-cortex-status).
+ * Default ON. `MEGACOMPACT_VC9A=0` disables and is byte-identical to the
+ * predecessor (VC8C-era shape): the endpoint returns `{enabled:false,
+ * mode:"C", status:"off"}` and surfaces no qualification/blocker/health detail —
+ * a pure reader-only projection, never a mutation. This flag MUST also be a
+ * dashboard SETTINGS toggle (visible in config UI, never in EXCLUDED_SETTINGS),
+ * mirroring VC4A..VC8C. The dashboard reader itself performs only local
+ * filesystem reads (no network, PREVENT-PI-004).
+ */
+export const VC9A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC9A");

package/src/config/vector-cortex.ts

@@ -275,6 +275,11 @@ export const VC8B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC8B");
 // import keeps resolving unchanged.
 export { VC8C_ENABLED } from "./vector-cortex-vc8c.js";
 
+// VC9A (setup-cortex status read path) extracted to vector-cortex-vc9a.ts to
+// keep this file under the 300-line soft limit. Re-exported here so every
+// existing `from "./config/vector-cortex.js"` import keeps resolving unchanged.
+export { VC9A_ENABLED } from "./vector-cortex-vc9a.js";
+
 // Breaker state machine constants (TRIAD_RESILIENCE.md §breaker) extracted to
 // vector-cortex-breakers.ts to keep this file under the 300-line soft limit.
 export {

package/src/config.ts

@@ -178,6 +178,7 @@ export {
   VC8A_ENABLED,
   VC8B_ENABLED,
   VC8C_ENABLED,
+  VC9A_ENABLED,
   BREAKER_WINDOW_MS,
   BREAKER_MIN_ATTEMPTS,
   BREAKER_PERF_FAILURES,