pi-mega-compact 0.20.25 → 0.20.27

package/dist/config/vector-cortex-vc9a.js

@@ -0,0 +1,29 @@
+/**
+ * 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 = () => sprintFlag("MEGACOMPACT_VC9A");

package/dist/config/vector-cortex.js

@@ -244,6 +244,10 @@ export const VC8B_ENABLED = () => sprintFlag("MEGACOMPACT_VC8B");
 // Re-exported here so every existing `from "./config/vector-cortex.js"`
 // 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 { BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./vector-cortex-breakers.js";

package/dist/config.js

@@ -114,4 +114,4 @@ export const NEW_UI = () => ragEnabled("MEGACOMPACT_NEW_UI");
 // default ON, `=0`/`_DISABLED` off. Re-exported from src/config/vector-cortex.ts
 // so root consumers share one source of truth.
 // ---------------------------------------------------------------------------
-export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, VC4A_ENABLED, VC4B_ENABLED, VC4C_ENABLED, VC5A_ENABLED, VC5B_ENABLED, VC5C_ENABLED, VC6A_ENABLED, VC6B_ENABLED, VC6C_ENABLED, VC7A_ENABLED, VC7B_ENABLED, VC7C_ENABLED, VC8A_ENABLED, VC8B_ENABLED, VC8C_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";
+export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, VC4A_ENABLED, VC4B_ENABLED, VC4C_ENABLED, VC5A_ENABLED, VC5B_ENABLED, VC5C_ENABLED, VC6A_ENABLED, VC6B_ENABLED, VC6C_ENABLED, VC7A_ENABLED, VC7B_ENABLED, VC7C_ENABLED, VC8A_ENABLED, VC8B_ENABLED, VC8C_ENABLED, VC9A_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";

package/dist/extensions/dashboard-server/api-contracts/endpoints/registry-ext.js

@@ -27,4 +27,11 @@ export const EXTRA_ENDPOINTS = {
         path: "/api/vector-cortex/ledger",
         description: "Reader-only occurrence-ledger identity view: seq/eventId/kind/digest + high-water (never source payloads).",
     },
+    // ─── VC9A Setup Cortex (dashboard Setup tab cortex status) ─────────
+    /** GET /api/setup-cortex-status — reader-only vector-cortex encoder gate. */
+    setupCortexStatus: {
+        method: "GET",
+        path: "/api/setup-cortex-status",
+        description: "Reader-only vector-cortex encoder gate: mode A/B/C, qualification verdict, blockers, encoder health — for the dashboard Setup tab. Never closes the ML gate.",
+    },
 };

package/dist/extensions/dashboard-server/api-contracts/setup-cortex.js

@@ -0,0 +1,12 @@
+/**
+ * api-contracts/setup-cortex.ts — Setup Cortex status API types (VC9A).
+ *
+ * Types for GET /api/setup-cortex-status, the reader-only aggregate that
+ * surfaces the vector-cortex encoder gate (mode A/B/C, qualification verdict,
+ * blockers, encoder health) in the dashboard Setup tab WITHOUT closing the ML
+ * gate. Reader-only: never payloads/prompts/ledger (EVAL-REDACT-002).
+ *
+ * PREVENT-PI-004: type definitions only, no network code.
+ * PREVENT-011: no `any` type — all types are explicit.
+ */
+export {};

package/dist/extensions/dashboard-server/route-dispatch.js

@@ -8,7 +8,7 @@
  * PREVENT-PI-004: local filesystem read only, no network.
  * PREVENT-011: no `any` type.
  */
-import { handleIndex, handleRepoIndex, handleEvents, handleGameState, handleGameScores, handlePerfSamples, handlePerf, handleAchievements, handleSessions, handleTopics, handleTurns, handleMaintenance, handleProviderCache, handleMemoryStatus, handleCacheStripes, handleSetupStatus, handleSetupDetect, handleSetupConfigure, handleMemoryMap, handleRaptorTree, handleRaptorBuildHistory, handleContextHealth, handleCachePoison, handleHealthSettings, handleEmbedderHealth, handleRagSettings, handleRagMetrics, handleModelThresholds, handleWiki, handleVectorCortexEvaluation, handleVectorCortexHealth, handleVectorCortexBreakersReset, handleVectorCortexLedger, handleVectorCortexTopology, handleVectorCortexQuery, handleVectorCortexShards, handleVectorCortexResidual, handleVectorCortexReconstruct, handleVectorCortexPlans, handleVectorCortexRender, handleVectorCortexRollout, handleVectorCortexClosureProof, handleVectorCortexRestore, } from "./routes.js";
+import { handleIndex, handleRepoIndex, handleEvents, handleGameState, handleGameScores, handlePerfSamples, handlePerf, handleAchievements, handleSessions, handleTopics, handleTurns, handleMaintenance, handleProviderCache, handleMemoryStatus, handleCacheStripes, handleSetupStatus, handleSetupDetect, handleSetupConfigure, handleMemoryMap, handleRaptorTree, handleRaptorBuildHistory, handleContextHealth, handleCachePoison, handleHealthSettings, handleEmbedderHealth, handleRagSettings, handleRagMetrics, handleModelThresholds, handleWiki, handleVectorCortexEvaluation, handleVectorCortexHealth, handleVectorCortexBreakersReset, handleVectorCortexLedger, handleVectorCortexTopology, handleVectorCortexQuery, handleVectorCortexShards, handleVectorCortexResidual, handleVectorCortexReconstruct, handleVectorCortexPlans, handleVectorCortexRender, handleVectorCortexRollout, handleVectorCortexClosureProof, handleVectorCortexRestore, handleSetupCortexStatus, } from "./routes.js";
 // VC6C repair lives in its own module (routes-vector-cortex-repair.ts) so the
 // heal route file stays well under the 400-line extension soft limit.
 import { handleVectorCortexRepair } from "./routes-vector-cortex-repair.js";
@@ -141,5 +141,7 @@ export function dispatchRoutes(req, res, ctx) {
         return true;
     if (handleVectorCortexPlatform(req, res, ctx))
         return true;
+    if (handleSetupCortexStatus(req, res, ctx))
+        return true;
     return false;
 }

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

@@ -48,5 +48,6 @@ export const VECTOR_CORTEX_SETTINGS = {
         boolDirect("MEGACOMPACT_VC8A", "VC8A Consent-Bound Outcomes", "Consent-bound outcome ledger and offline learning dataset. Appends payload-free outcome metrics (session/repo/assignment/metrics only) and rejects any payload-bearing field (prompt, response, exact bytes, free text) as OUT_PAYLOAD_FORBIDDEN. Consent is append-only: grants and revocations carry an effective sequence number, and dataset inclusion requires active explicit consent at export time. Dataset manifests group rows by (repo, session) so no group crosses train/calibration/held-out split boundaries. Revocations disappear from future manifests. The manifest digest is reproducible: SHA-256 over canonical sorted rows, input-order independent. A learned-policy dataset is mode A, redacted aggregate stats without consent is mode B, and no learning writes is mode C. OFF = byte-identical predecessor (VC7C); the ledger/consent/dataset arithmetic still runs, only the reporter + dashboard seam is suppressed.", true),
         boolDirect("MEGACOMPACT_VC8B", "VC8B Shadow Adaptive Policy", "Bounded shadow adaptive policy + M7 pressure-v2 migration. Policy actions are from a finite set (admit/dampen/defer/escalate/reject) chosen deterministically by the canonical pressure level; token budgets are clamped into a configured window after the pressure factor. Unknown pressure labels are rejected as POL_PRESSURE_UNKNOWN, never coerced to a neighbour. The shadow engine is structurally incapable of affecting the live path: inputs are deep-copied, the canonical prompt digest is pinned before and after to prove non-mutation, and liveMutations is always zero. M7 migrates legacy pressure labels to the v2 canonical five by copy/validate/switch; an unknown label blocks the switch and keeps the legacy pointer (M7_PRESSURE_UNKNOWN). A shadow decision is mode A, static calibrated policy is mode B (forced by invalid A), and fixed legacy thresholds is mode C (forced by M7 or B failure). OFF = byte-identical predecessor (VC8A); the policy/shadow/migration arithmetic still runs, only the reporter + dashboard seam is suppressed.", true),
         boolDirect("MEGACOMPACT_VC8C", "VC8C Canary Platform + Rust Parity", "Canary selection and external Rust parity. The selector admits a qualified external Rust artifact only when ABI version, URL metadata, commit, Cargo.lock digest, and platform all match evidence; a Cargo.lock digest mismatch rejects the artifact (RUST_CARGO_DIGEST_MISMATCH). The cross-conformance runner exchanges length-framed neutral records over a local stdin/stdout channel — a subprocess, never a URL (PREVENT-PI-004). A parity mismatch selects TS mode B. A qualified external artifact is mode A, TS reference is mode B, legacy path is mode C. OFF = byte-identical predecessor (VC8B); the selector and cross-conformance arithmetic still run, only the reporter + dashboard seam is suppressed.", true),
+        boolDirect("MEGACOMPACT_VC9A", "VC9A Setup Cortex Status", "Reader-only Setup Cortex status read path (GET /api/setup-cortex-status): surfaces the vector-cortex encoder gate — mode A/B/C, qualification verdict, open blockers, encoder health — to the dashboard Setup tab without closing the ML gate. OFF = byte-identical predecessor (VC8C-era): returns enabled:false / mode:C / status:off.", true),
     ],
 };

package/dist/extensions/dashboard-server/routes-setup-cortex.js

@@ -0,0 +1,143 @@
+/**
+ * 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 { createHash } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+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";
+/** Resolve the committed encoder-v1 asset dir by walking up to the repo root. */
+function encoderAssetDir() {
+    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;
+}
+let factCache = null;
+/** Stable cache key: manifest bytes + (size,mtime) of the asset files + platform. */
+function factCacheKey(dir, manifestPath) {
+    const platform = detectPlatform();
+    if (!platform)
+        return null;
+    const parts = [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) {
+    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;
+    try {
+        // guardrails-allow PREVENT-PI-004: local manifest filesystem read (loopback)
+        digest = createHash("sha256").update(readFileSync(manifestPath)).digest("hex");
+    }
+    catch {
+        const facts = { 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 = 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() {
+    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, res, _ctx) {
+    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 = enabled ? [...SETUP_CORTEX_BLOCKERS] : [];
+    const body = {
+        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/dist/extensions/dashboard-server/routes.js

@@ -24,3 +24,4 @@ export { handleRagMetrics } from "./routes-rag-metrics.js";
 export { handleModelThresholds } from "./routes-model-thresholds.js";
 export { handleWiki } from "./routes-wiki.js";
 export { handleVectorCortexEvaluation, handleVectorCortexHealth, handleVectorCortexBreakersReset, handleVectorCortexLedger, handleVectorCortexTopology, handleVectorCortexQuery, handleVectorCortexShards, handleVectorCortexResidual, handleVectorCortexReconstruct, handleVectorCortexPlans, handleVectorCortexRender, handleVectorCortexRollout, handleVectorCortexClosureProof, handleVectorCortexRestore, } from "./routes-vector-cortex.js";
+export { handleSetupCortexStatus } from "./routes-setup-cortex.js";

package/dist/extensions/dashboard-server/server.js

@@ -254,9 +254,11 @@ export async function launchDashboardServer(stateDir) {
                     }));
                     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/dist/extensions/dashboard-server/setup-cortex-blockers.js

@@ -0,0 +1,53 @@
+/**
+ * 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 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 = [
+    {
+        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) {
+    return SETUP_CORTEX_BLOCKERS.find((b) => b.id === id);
+}

package/dist/extensions/mega-dashboard-bounce.js

@@ -0,0 +1,79 @@
+/**
+ * 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() {
+    stalenessCheckedThisProcess = false;
+}
+/**
+ * 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) {
+    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;
+        let from = 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/dist/extensions/mega-dashboard-cmds.js

@@ -9,6 +9,11 @@ import { join, dirname, sep } from "node:path";
 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 { bounceStaleRunnerIfAny, } 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 } from "./mega-dashboard-bounce.js";
 /** Register the dashboard server lifecycle commands. */
 export function registerDashboardCommands(pi, runtime) {
     // H3 fix: read currentStateDir at CALL time, not registration time. The
@@ -118,6 +123,27 @@ export function registerDashboardCommands(pi, runtime) {
         }
         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() {
+        try {
+            const info = JSON.parse(readFileSync(portFile(), "utf-8"));
+            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) {
+        return { isServerRunning, serverVersion, markerVersion, ownVersion, killServerOnPort, notify };
+    }
     /**
      * Resolve the launchable dashboard-server module.
      *
@@ -157,9 +183,14 @@ export function registerDashboardCommands(pi, runtime) {
         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 */ }`,
@@ -188,31 +219,18 @@ export function registerDashboardCommands(pi, runtime) {
         description: "Start the local web dashboard and optionally open it in the default browser.",
         handler: async (_args, ctx) => {
             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
             ctx.ui.notify("[mega-compact] starting dashboard server…");
@@ -332,4 +350,19 @@ export function registerDashboardCommands(pi, runtime) {
             }
         },
     });
+    // 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(() => { }));
+        }
+        catch {
+            /* best-effort — never break the session */
+        }
+    });
 }

package/dist/src/config/vector-cortex-vc9a.js

@@ -0,0 +1,29 @@
+/**
+ * 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 = () => sprintFlag("MEGACOMPACT_VC9A");

package/dist/src/config/vector-cortex.js

@@ -244,6 +244,10 @@ export const VC8B_ENABLED = () => sprintFlag("MEGACOMPACT_VC8B");
 // Re-exported here so every existing `from "./config/vector-cortex.js"`
 // 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 { BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./vector-cortex-breakers.js";

package/dist/src/config.js

@@ -114,4 +114,4 @@ export const NEW_UI = () => ragEnabled("MEGACOMPACT_NEW_UI");
 // default ON, `=0`/`_DISABLED` off. Re-exported from src/config/vector-cortex.ts
 // so root consumers share one source of truth.
 // ---------------------------------------------------------------------------
-export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, VC4A_ENABLED, VC4B_ENABLED, VC4C_ENABLED, VC5A_ENABLED, VC5B_ENABLED, VC5C_ENABLED, VC6A_ENABLED, VC6B_ENABLED, VC6C_ENABLED, VC7A_ENABLED, VC7B_ENABLED, VC7C_ENABLED, VC8A_ENABLED, VC8B_ENABLED, VC8C_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";
+export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, VC2A_ENABLED, VC2B_ENABLED, VC2C_ENABLED, VC3A_ENABLED, VC3B_ENABLED, VC3C_ENABLED, VC4A_ENABLED, VC4B_ENABLED, VC4C_ENABLED, VC5A_ENABLED, VC5B_ENABLED, VC5C_ENABLED, VC6A_ENABLED, VC6B_ENABLED, VC6C_ENABLED, VC7A_ENABLED, VC7B_ENABLED, VC7C_ENABLED, VC8A_ENABLED, VC8B_ENABLED, VC8C_ENABLED, VC9A_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";